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Discussion 


The  CRRES  Electric  Field/Langmuir  I^obe  instruments  consisted  of  a  main  electronics  package  (m  the 
spacecraft  body  and  two  pairs  of  orthogonal  sensors  with  tip-to-tip  separations  of  about  100  meters  in  the  spin  plane 
of  the  spacecraft.  One  pair  of  sensors  were  spherical  probes  and  the  other  pair  were  cylindrical  antennas.  The  instru¬ 
ment  provided  measurements  of  the  quasistatic  two-dimensional  electric  field  in  the  spin  plane  of  the  spacecraft  at  a 
rate  of  32  samples/s.  a  sensitivity  of  better  than  0. 1  mV/m,  and  a  dynamic  range  of  1000  mV/m.  The  spherical  probes 
were  periodically  swept  in  either  current  or  voltage  to  determine  plasma  density  and  temperature  through  ground 
analysis  of  the  resulting  Langmuir  characteristic  curve.  The  measurement  was  accurate  for  densities  between  0.1  and 
10.000  electrons/cm^  and  electron  temperatures  ranging  from  a  fraction  of  an  eV  to  100  eV.  The  instrument  also  had 
a  programmable  burst  memory  which  provided  selected  high  time  resolution  data  at  cumulative  rates  up  to  50,000 
samples/s. 

The  CRRES  orbit,  from  258  km  at  perigee  to  33,584  km  at  apogee,  allowed  extensive  measurements,  at  all 
local  times,  throughout  the  radial  extent  of  the  plasmaspheie.  ring  current,  and  radiation  belts  of  the  Earth.  The 
spacecraft  also  spent  significant  periods  of  time  in  the  near-Eatth  plasmasbeet  during  magnetically  disturbed  periods. 
The  instrument  measured  electric  fields  associated  with  injecdmi  of  plasmasheet  particles  into  the  inner  magneto¬ 
sphere:  the  wave  mode  responsible  for  particle  loss  through  precipitation  into  the  ionosphere;  the  role  of  electric 
fields  in  radiation  belt  particle  energization;  and  plasma  processes  which  couple  along  the  magnetic  field  line  to  pro¬ 
duce  acceleration  of  electrons  to  form  auroral  arcs  at  lower  altitudes.  In  addition,  the  instrument  provided  measure¬ 
ments  during  both  high-  and  low-altitude  barium  and  lithium  releases.  Seme  examples  of  the  data  that  have  been 
analyzed  are  presented  below. 

An  example  of  early  data  from  the  CRRES  instrument  is  presented  in  Figure  1.  Illustrated  in  the  tt^  panel 
are  density  fluctuatioas  measured  by  spherical  double  probes,  in  the  middle  panel  are  electric  field  fluctuations  mea¬ 
sured  by  the  cylindrical  double  probes,  and  the  lower  panel  illustrates  magnetic  field  fluctuations  measured  by  an 
instrument  provided  by  the  University  of  Iowa.  This  example  is  a  whistler  wave  that  is  modulated  on  a  30  ms  time 
scale  and  that  appears  in  density  cavities. 

In  situ  measurements  of  electric  and  magnetic  fields  were  obtained  during  a  laige  ionospheric  barium  release 
on  July  19,  1991.  While  previous  measurements  of  chemical  releases  have  shown  that  Alfv^n  waves  are  excited, 
these  CRRES  measurements  provided  the  first  direct  evidence  for  the  magnetic  braking  of  a  plasma  cloud  through  the 
formation  of  intense  Alfv^n  waves  standing  in  the  release  frame.  The  electric  field  measurements  show  a  300  mV/m 
perturbation  associated  with  the  motion  of  the  release  plasma  relative  to  the  ambient  medium  (see  Figure  2).  (Zbinci- 
dent  with  the  electric  field  variation,  an  intense  magnetic  field  perturbation  (6(X)  nT)  was  observed  and  attributed  to  a 
field-aligned  current  system.  We  estimate  that  the  JxB  force  due  to  the  perpendicular  closure  of  this  field-aligned  cur¬ 
rent  (0.5  A/m)  can  transfer  momentum  from  the  release  to  the  ambient  medium  at  a  rate  consistent  with  the  measured 
deceleration  time  scale  (1-2  seconds)  obtained  from  LANL  ground-based  optical  observers.  The  ratio.  bEIbB.  is 
about  equal  to  the  Alfv^n  velocity.  In  addition,  as  displayed  in  Figure  3.  other  features  of  this  release  include  obser¬ 
vations  of  intense  low-frequency  electrostatic  fluctuations  (100  mV/m)  polarized  perpendicular  to  the  magnetic  field 
at  the  release  boundary,  and  a  variety  of  Alfv^nic  fluctuations  observed  inside  and  outside  the  release. 

Similar  data  were  obtained  during  barium  releases  at  altitudes  between  the  ionosphere  and  L  =  7.25.  A  sum¬ 
mary  of  the  measured  duration  of  the  perturbed  electric  field  as  compared  to  a  theoretical  estimate  of  the  cloud  decel¬ 
eration  time  in  an  Alfv^n  wing  deceleration  model  is  given  in  Figure  4.  The  proportionality  between  theory  and 
experiment  suggests  that,  at  all  altitudes,  the  barium  cloud  is  braked  by  Alfvdn  wave  interactions. 

Another  interesting  example  from  the  CRRES  data  set  involves  an  encounter  of  the  Earth's  magnetosphere 
with  an  interplanetary  shock  on  March  23.  1991.  at  about  3:41  UT.  At  this  time,  the  spacecraft  was  at  about  L=2.6 
and  3:00  MLT  near  the  equatorial  plane.  During  the  sudden  commencement  associated  with  this  shock,  for  approxi¬ 
mately  90  seconds,  the  electric  and  magnetic  field  detectors  observed  some  of  the  largest  variatiems  ever  observed  in 
the  inner  magnetosphere.  These  observations  coincided  with  the  formation  near  L=2.6  of  a  new  electrrm  radiatirm 
belt  with  fluxes  3-4  orders  of  magnitude  larger  than  the  previously  observed  electron  fluxes  at  15  MeV.  The  time 
scale  associated  with  the  formation  of  the  new  belt  was  a  fraction  of  a  15  MeV  drift  period.  As  has  been  previously 
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reported,  the  observed  fluxes  of  etectrons  in  the  15-30  MeV  range  dominated  over  pre-existing  belt  fluxes  by  two 
orders  of  magnitude  for  the  remaining  six  months  of  the  CRRES  lifetime.  The  electric  field  measurements  are  the 
first  such  observations  of  a  shock-induced  sudden  commencement  in  the  irmer  magnetosphere.  The  60  mV/m  (peak- 
to-peak)  variations  in  the  electric  field  observed  during  this  event  are  an  order  of  magnitude  larger  than  the  largest 
sudden-commencement  field  observed  by  the  GEOS  electric  field  experiment.  They  are  two  to  three  ori'ers  of  magni¬ 
tude  larger  than  the  typical  electric  field  seen  at  L=2.6  and  also  two  orders  of  magnitude  larger  than  the  0. 1  - 1  mV/m 
electric  field  fluctuations  thought  to  drive  the  stochastic  processes  of  radial  difiusion  and  particle  ene  giza'tion  in  the 
irmer  magnetosphere  over  much  longer  periods  of  time.  Since  radial  diffusion  coefficicuis  scale  with  the  square  of 
the  electric  field  fluctuation  amplitude,  these  large  amplitucte electric  fields  which  resulted  in  a  “single  step”  accelera¬ 
tion  of  particles  were  probably  four  to  six  (xders  of  magnitude  more  efficient  in  transporting  and  energizing  panicles 
than  multi-step  radial  diffiision  processes.  A  summary  of  the  electric  field  and  particle  measurements  is  presented  in 
Figures. 


Another  significant  result  from  the  CRRES  research  program  was  the  development  of  general  purpose  soft¬ 
ware  for  processing,  analyzing,  and  displaying  electric  and  magnetic  field  data.  The  status  of  this  effort  is: 

1.  Survey  data  files  and  plots  at  spin-time  resolutioD  have  been  created  for  all  1045  orbits  which  contain 
Langmuir  Probe  telemetry. 

2.  A  number  of  derived  science  quantities  have  been  added  to  the  current  interactive  ( !RRES  viewing  pro¬ 
gram.  These  include: 

Software-generated  E-field  spin  fits 
V  X  B  subtraction 
Spin  period 

Angle  between  cylinder  E-fidd  and  sphere  E-field 

Angles  between  E-field  and  V  x  B 

Angle  between  Y-MGSE  and  boons 

Ratios  of  components  of  E-field  and  V  x  B  subtractions 

Sphere  and  cylinder  boom  positions  in  EQ 

X-component  of  E-field  by  use  of  E  •  B  =  0 

Sine-wave  subtractitm 

3.  Software  least-squares  spin  fits  have  been  performed  and  stored  in  files  for  every  (rrl^it  with  Langmuir 
Probe  telemetry. 

4.  The  CRRES  viewing  program  ouq)uts  ASCII  files  with  an  arbitrary  selection  of  the  instrument  and 
physics  quantities  that  are  available  for  plotting. 

5.  The  CRRES  viewing  program  operates  in  unattended  batch  mode  to  create  hardcopy  plots  or  ASCII  file 
output. 

6.  A  new  version  of  the  interactive  CRRES  viewing  program  is  under  development  and  is  currently  80% 
complete.  It  is  described  in  the  following  documents,  attached  as  Appendices  and  B,  respectively  . 
“Functional  Description  of  the  New  Version  of  the  ‘Fiche’  Software  "  and  “Conceptual  Design  of  the 
CRRES  Software.” 

Ongoing  activities  at  the  end  of  this  contract  are  completion  of  the  automated  data  rcductron  and  presenta¬ 
tion  program  and  continuing  analyses  of  the  average  DC  electric  field  inside  L=7.  ion  cyclonon  waves  in  the  ring  cur¬ 
rent.  the  formation  of  trapped  particle  radiation  belts  due  to  sudden-commencement  electric  fields,  relation  of  the 
plasmapause  location  to  penetrating  electric  fields,  the  normal  component  of  the  electric  field  at  the  plasmasheet 
boundary  layer,  and  small-scale  electric  fields  near  the  inner  edge  of  the  ring  current. 

A  list  of  publications  resulting  fixm  the  work  completed  to  date  is  attached  as  Appendix  C. 
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Fig.  1.  Observations  of  whistler  wave  packets  imbedded  in  10-100  second  density  depletions  from  the  UCB/AFGL 
Langmuir  Probe/Electric  Field  Experiment  oo  GIRES.  The  data  was  obtained  through  instrument  burst  memory  at  a 
data  rate  of  10^  samples/sec. 


Fig.  2.  In  situ  measurements  of  electric  fields,  spacecrafi  potential,  and  magnetic  fields  over  a  ten-second  interval 
containing  a  large  barium  chemical  release  at  ionospheric  altitudes.  Both  electric  and  magnetic  field  data  are  pre¬ 
sented  in  a  sensor  coordinate  system  rotating  with  the  spacecraft.  Hie  data  is  also  presented  in  the  spacecraft  frame. 

Fig.  3.  This  figure  shows  an  enlarged  view  of  the  electric  field  component  nearly  perpendicular  to  the  spacecraft 
velocity  and  the  local  magnetic  field  direction  (panel  1)  and  the  magnetic  field  measurement  along  the  spacecraft 
velocity  vector.  The  electric  and  magnetic  field  measurements  provide  evidence  for  an  Alfvhn  wave  propagating 
along  B  which  act  to  decelerate  the  release  on  a  time  scale  of  1-2  seconds. 

Fig.  4.  Comparison  of  the  measured  deceleration  time  scale  of  six  plasma  clouds  to  that  predicted  (t*)  from  Alfvhn 
wings. 

Fig.  5.  Measurement  of  the  YGSE  component  cf  the  electric  field  and  electron  count  rates  fi-om  four  energetic  parti¬ 
cle  detectors  ranging  in  amplitude  from  >6  MeV  to  10  -  50  MeV.  The  spacecraft  was  located  at  L  =  2.5  and  MLT  = 
2.5.  The  spacecraft  observed  large-amplitude  electric  fields  and  drift  echo  electrons  as  the  first  step  in  formation  of  a 
new  radiation  belt  on  March  24.  3;41  UT  when  the  Earth  encountered  an  interplanetary  shock. 
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Appendix  A 


Functional  Description  of  the  New  Version  of  the  "Fiche"  Software 


I.  Facilities  and  Expectations 

The  New  Version  of  the  "Fiche”  Software  running  on  a  Sun  SparcII  Workstation  using  CRRES 
satellite  data  and  its  associated  science  algorithms  will  allow  a  user  to  view  either  raw  instrument 
data  quantities  (see  APPENDIX  I  for  a  listing)  or  data  which  results  from  CRRES  related  S  ience 
Algorithms  (see  APPENDIX  II  for  a  listing)  in  an  interactive  manner. 

The  user  will  accomplish  this  by  starting  the  CRRES  "Fiche"  Software.  The  user  will  then  be 
expected  to  select  an  appropriate  timespan  (corresponding  to  a  data  file  or  files  containing  the 
orbit  or  orbits)  and  to  indicate  a  set  of  quantities  one  wishes  to  view.  This  may  be  accomplished 
piece-meal  or  by  selecting  a  previously  defined  configuration  file.  At  this  point  the  decommutator 
will  begin  decoding  all  of  the  raw  data  from  the  orbit  files  followed  by  the  computation  of 
requested  science  quantities.  As  the  raw  instrument  quantities  are  unpacked  and  as  the  scientific 
quantities  are  computed  the  data  will  be  displayed  on  in  the  user  interface  plot  panels  in  a  "real- 
time"  manner. 

The  user  may  then  pan  through  the  data,  zoom-in,  zoom-out,  scale  the  data  up  or  down  for  finer 
granularity,  select  different  numbers  of  points,  select  a  new  timespan  for  viewing,  add  new  plot 
panels,  delete  existing  plot  panels,  rearrange  the  current  plot  list,  save  the  current  configuration, 
select  a  new  configuration,  or  otherwise  set  his^er  view  of  the  data;  in  short  the  user  can  perform 
any  of  the  existent  functions  of  the  current  version  of  the  "Fiche"  Software. 

The  user  can  realistically  expect  instant  replotting  of  CRRES  raw  data  quantities  as  long  as  one 
stays  within  the  requested  timespan.  This  is  possible  since  all  of  the  raw  data  is  decommutated  at 
the  time  of  timespan  request  and  is  stored  in  contiguous  memory  arrays.  These  can  be  accessed 
very  quickly  by  the  software  and  can  therefore  provide  this  performance.  When  a  new  timespan 
is  requested,  however,  the  decommutator  will  decode  all  of  the  raw  data  at  that  time.  The  user  can 
expect  this,  again,  to  take  several  minutes.  Thus  the  user  optimizes  his/her  time  by  selecting  judi¬ 
ciously  the  timespan  in  which  he/she  is  interested.  Note  that  the  larger  the  time-span  the  larger 
the  amount  of  memory  needed  to  hold  the  data.  The  user  will  be  restricted  at  the  upper  end  of 
length  of  allowable  timespan  by  the  amount  of  available  system  memory. 

The  CRRES  Scientific  Computation  data  quantities,  on  the  other  hand,  are  calculated  on  an  as 
requested  basis  for  a  panicular  viewing  timespan.  This  is  the  case  because  the  computations  are 
generally  very  time  consuming  compared  to  the  decommutation  of  raw  data  and  the  amount  of 
available  system  memory  is  far  to  small  to  hold  all  of  the  available  "Science  Quantitites".  Com¬ 
putations  on  all  points  for  an  hour’s  wort,  of  Electric  Field  data  (32  points/second)  could  take  on 
the  scale  of  (30)?  seconds.  Furthermore,  if  a  user  is  zoomed  in  to  a  particular  level  and  the  user 
chooses  another  viewing  timespan  (larger  or  smaller)  by  zooming  out/in,  the  science  quantities 
will  be  recomputed  for  the  new  viewing  timespan.  Since  the  time  needed  to  yield  the  desired  sci¬ 
entific  quantities  is  considerable  and  they  will  be  recomputed  often,  an  option  ‘  ill  exist  to  cull 
down  the  number  of  points  computed  for  a  given  timespan.  This  will,  in  turn,  proportionally 
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reduce  the  amount  of  time  required  to  complete  the  computations.  This  can  be  used  lO  opiinuze 
one's  use  of  time.  Thus  the  user,  here,  optimizes  his/her  time  by  setting  the  number  of  points  to  a 
small  value  until  he/she  closes  in  on  the  particular  data  he/she  wishes  to  view.  It  is  important  to 
note  here  that  the  memory  resident  raw  instrument  data,  along  with  the  restructuring  of  the  sof- 
ware  should  be  expected  to  improve  performance  of  even  these  time  consuming  Scic'ce  Algo 
rithms  over  the  present  version. 

The  New  Version  of  the  "Fiche"  Software  will  also  provide  facilities  for  getting  output  such  as 
printed  plots  &  ascii  dumps  and  for  running  plots  in  a  batch  mode. 


n.  Computing  Standards 

The  New  Version  of  the  "Fiche"  Software  will  be  developed  on  a  Sun  Sparc  II  Workstation  with 
64  MegaBytes  of  memory  and  a  2  GigaByte  hard  disk  running  Sun  UNIX.  The  goal  of  the  devel¬ 
opers  will  be  to  develop  portable  software  which  will  run  on  most  Standard  UNIX  Workstations 
or  Minis  which  have  enough  memory  (RAM  or  virtual)  to  hold  the  application  data  (>50  Mega- 
Bytes  for  CRRES)  and  enough  disk  space  (>35  MegaBytes)  to  support  Sun  Mapped  Memorj- 
plus  whatever  is  necessary  to  hold  the  data  files  and  to  suppon  the  virtual  memory'  requirements. 

More  specifically,  the  developers  will  support  at  a  minimum  any  of  these  machines  running  stan¬ 
dard  UNIX  which  supports  Shared  and/or  Mapped  Memory,  TCPIP,  and  Sockets  or  TLl  (or  Sun 
RPC).  For  Graphics  suppon,  the  New  Version  of  the  "Fiche"  Software  will  suppon  Xlib  and 
eventually  either  MOTIF  or  OpenLxxjk. 

This  Software  will  be  developed  primarily  in  the  ANSI  standard  'C  programming  language.  In 
addition  to  this,  the  developers  hope  to  expand  this  base  and  implement  portions  of  the  code  in  a 
'C  superset,  C++,  where  a  clear  cut  advantage  exists  to  using  the  C++  object  oriented  style  of  pro¬ 
gramming. 


ni.  Extensibility 

Since  the  developers  of  the  "Fiche”  Software  cannot  foresee  all  the  possible  applications  and  con¬ 
figurations  for  this  software,  the  above  computing  standards  represent  the  mimmuir.  baseline  tar¬ 
gets  for  initial  development.  This  is  not  to  say  that  further  support  and  development  for  future 
configurations  or  applications  will  not  be  available,  but  rather  that  these  are  the  minimum  facili¬ 
ties  which  will  be  supported  for  the  initial  implementation  of  the  New  Version  of  the  Fiche"  Soft¬ 
ware.  Future  support  and  development  will  be  carried  on  in  several  areas;  namely  addition  of 
more  advance  and  needed  science  algorithms  by  either  CRRES  developers  or  by  independent  pro¬ 
grammers,  support  for  future  instruments,  portability  of  this  software  to  other  platforms,  and  pos 
sibly  a  version  that  may  be  run  over  a  network.  These  extensions  and  advancements  will  be  taken 
into  consideration  and  the  software  will  be  designed  to  facilitate  the  addition  of  these  capabilities. 

The  first  of  these  extensions  will  be  the  addition  of  further  Science  Algorithm.s  There  will  be 
two  separate  ways  of  accomplishing  this;  one  will  be  to  simply  add  the  new  algorithm  to  the 
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existing  CRRES  Science  Algorithm  Module  and  the  other  will  be  to  essentially  create  another 
versions  of  the  Science  Algorithm  Module  which  will  look  and  behave  exactly  like  it,  but  which 
will  implement  different  computations.  This  second  type  of  interface  may  support  Fortran,  and 
possibly,  far  in  the  future,  DDL. 

Cenainly  the  use  of  the  main  portion  of  this  software  for  future  satellites,  namely  POLAR,  CLUS¬ 
TER,  and  FAST,  is  required  Although  the  new  satellites  will  have  their  own  decommutator 
decoding  scheme  and  its  own  associated  science  computations,  the  user  interface.  Science  Algo¬ 
rithm  and  Decommutator  Super  structure  will  be  identical.  This  will  leave  any  modification  and 
development  for  future  satellites  to  those  sections  which  are  specific  to  that  instrument.  As  a  pos¬ 
sibility,  other  instruments  may  be  supported  (e.g.  rockets,  file  formats,  etc.).  At  a  minimum,  very 
well  defined  interfaces  will  exist  which  will  allow  developers  from  other  instruments  to  create 
their  own  software  to  attach  to  the  main  portion  of  the  CRRES  "Fiche"  Software  and  provide  its 
facilities. 

In  the  above  case  it  may  be  desirable  to  port  this  software  to  other  types  of  systems  (hardware  and 
OS).  The  developers  will  attempt  to  support  this  portability  in  the  following  limited  way:  The 
developers  will  attempt  to  use  the  ANSI  standard  'C  language  and  a  standard  library  (Xlib,  etc.)  to 
promote  easy  conversion  to  other  compilers.  The  support  of  Shared  or  Mapped  memory  will 
have  to  be  rewritten  by  the  users  whose  systems  cannot  support  it. 

The  last  extension  which  will  be  discussed  is  the  possibility  of  running  the  separate  functional 
parts  of  the  software  over  a  network  for  more  beneficial  resource  allocation  (i.e.  running  the 
decommutator  and  science  algorithms  from  a  powerful  machine  and  leaving  the  lesser  tasks  of 
the  user  interface  for  a  local  terminal).  This  will  be  supported  by  the  separation  of  the  software 
into  large  functional  blocks  of  standalone  processes.  These  will  be  able  to  run  independently  of 
the  (location  oO  the  other  programs  and  thus  will  be  more  easily  configured  to  meet  the  require¬ 
ments  of  network  operation. 


These  are  the  facilities  and  goals  for  the  New  Version  of  the  "Fiche"  Software.  Our  aim  is  to  pro¬ 
vide  the  excellent  facilities  for  data  analysis  which  are  available  in  the  current  software  while  pro¬ 
viding  opponunities  for  easy  modification,  adaptation,  and  expansion  in  the  future. 


APPENDIX  I 


CRRES  Raw  Instrument  Data 

Fast  Digital  Monitor 

FDM  Current/Voltage  mode 

FDM  Command  Error  Count 

FDM  Test  Calibrate  mode 

FDM  Bias  Sweep 

FDM  Playback  on/off 

FDM  Playback  Main/Burst 

FDM  Burst  condition  (l=searchJ2=collect3=wait) 

V3  (cylinder)  (mux  3) 

V2  (sphere)  (mux  4) 

VI  -  voltage  mode  only  (sphere)  (mux  5) 

VI  both  voltage  and  current  mode  (mux  6) 

VI2  voltage  difTerence  spheres  (mux  8) 

V12  through  BP  Filter  F3  (2048  Hz  center  freq)  (mux  9) 
V12  through  BP  Filter  F2  (256  Hz  center  freq)  (mux  10) 
V12  through  BP  Filter  FI  (32  Hz  center  freq)  (mux  11) 
V4  (cylinder)  (mux  12) 

VI2  unfiltered  (mux  14) 

V34  voltage  difference  cylinders  (mux  15) 

R12  current  from  sphere  2  (mux  4) 

Search  Coil  (mux  5) 

RIl  current  from  sphere  1  (mux  8) 

RIl  through  BP  Filter  F3  (2048  Hz  center  freq)  (mux  9) 
Rll  through  BP  Filter  F2  (256  Hz  center  freq)  (mux  10) 
Rll  through  BP  Filter  FI  (32  Hz  center  freq)  (mux  11) 
Rll  current  from  sphere  1  -  unfiltered  (mux  14) 
Magnetometer  BZ 
Magnetometer  BY 
Magnetometer  BX 
Burst  BZ  (bmux  0) 

Burst  BX  (bmux  1) 

Burst  BY  (bmux  2) 

Burst  V3  (bmux  3) 

Burst  V4  (bmux  4) 

Burst  V34  (bmux  5) 

Burst  V34  AC  (bmux  6) 

Burst  V 1  •  voltage  mode  (bmux  7) 

Burst  V12  AC  (bmux  8) 

Burst  V2  (bmux  9) 

Burst  VI  (bmux  10) 

Burst  V12  (bmux  11) 

Burst  Direct  ACC  (bmux  12) 

Burst  AGC  unfiltered  (bmux  13) 

Burst  Guard  1  (bmux  14) 

Burst  Stub  1  (bmux  15) 

Burst  Search  Coil  (bmux  7) 

Burst  Rll  AC  (bmux  8) 

Burst  RI2  current  (bmux  9) 


Burst  RIl  (bmux  10) 

DSC  Number  signed  ### 

DSC  Number  unsigned  ### 

DSC  Sun  angle 
DSC  Sun  period 
Raw  Mux  Channel  ### 

Bias  value  (Voltage  mode) 

VI  Bias  Sweep 
V2  Bias  Sweep 
V3  Bias  Sweep 
V4  Bias  Sweep 
Bias  value  (Current  mode) 

11  Bias  Sweep 

12  Bias  Sweep 

Diagnostic  Bias  stepping  (RAM  quantity) 
Spheres:  Spin  FitSnCoefficient  AHI 
Spheres:  Spin  FitNnCoefficient  ALO 
Spheres:  Spin  FitSnCoefficient  B 
Spheres:  Spin  FitNnCoefficient  C 
Spheres:  Spin  FitSnStd.  Deviation 
S{rfteres:SnPoints  in  Spin  Fit 
Spheres:\nSQRT  (BNu2  +  CSu2) 

Cylinders:  Spin  FitNnCoefficient  AHI 

Cylinders:  Spin  FitSnCoefficient  ALO 

Cylinders:  Spin  FitSnCoefficient  B 

Cylinders:  Spin  FitSnCoefficient  C 

Cylinders:  Spin  FitSnStd.  Deviation 

Cylinders:SnPoints  in  Spin  Fit 

Cylinders:SnSQRT  (BSu2  +  CSu2) 

EySnSphere 

EzSnSphcre 

EySnCylindcr 

EzSnCylinder 

Sphcrcs;32pl  Spin  FitNnCoefficient  AHI 
Spheres:32pt  Spin  FitNnCoefficient  ALO 
SpheFes:32pt  Spin  FitSnCoefficient  B 
Spheres:32pt  Spin  FitSnCoefficient  C 
Spheres:32pt  Spin  FitSnStd.  Deviation 
Spheres:  32ptSnPoints  in  Spin  Fit 
Sphercs:32ptSnSQRT  (BSu2  +  Ou2) 
Sphercs:32pt  Spin  FitNnCoefficient  D 
Cylindcrs:32pt  Spin  FitNnCoefficient  AHI 
Cylinders:32pt  Spin  FitNnCoefficient  ALO 
Cylinders:32pt  Spin  FitSnCoefficient  B 
Cylinders:32pt  Spin  FitSnCoefficient  C 
Cylinders:32pt  Spin  FitSnStd.  Deviation 
Cylinders:32ptSnPoinls  in  Spin  Fit 
Cylinders:32piNnSQRT  (BSu2  +  CSu2) 
Cylinders:32pt  Spin  FitSnCoefficient  D 
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CRRES  Data  from  Scientific  Calculations 


LSQ  Fit  and  Subtract  from  Current  Plot 
Bias  Sweep  Linear  Fit 
Temp 
Density 

Bias  Sweep  Exp.  Fit 
Temp 
Density 
Bias  Setting 

Power  Spectrum  (Fourier) 

B  components,  MAG 

B  components,  SC 

B  components,  ECI 

B  components,  GSE 

B  components,  MGSE 

B  components,  ECI,  model  subtracted 

B  components,  GSE,  model  subtracted 

B  components,  MGSE,  model  subtracted 

mag  of  B  (MAG  coords) 

mag  of  B  (SC  coords) 

mag  of  B  (ECI  coords) 

mag  of  B  (GSE  coords) 

mag  of  B  (MGSE  coords) 

mag  of  B*modeI  (ECI) 

mag  of  B-model  (GSE) 

vXB-x  (MGSE) 

vXB-y  (MGSE) 

vXB-z  (MGSE) 

vcorotXB-x  (MGSE) 

vcorotXB-y  (MGSE) 

vcoroiXB-z  (MGSE) 

vXB(mod)-x  (MGSE) 

vXB(mod)-y  (MGSE) 

vXB(mod)-z  (MGSE) 

Sph  SpinFit-vXB(mod)'y 
Sph  SpinFit-vXB(mod>z 
Cyl  SpinFit-vXB(mod)-y 
Cyl  SpinFit-vXB(mod)-z 
sqn(vXB-y^2+vXB-z''2) 

Sphere  SpinFit-vXB-y 
Sphere  SpinFit-vXB-z 
Cylinder  SpinFit-vXB-y 
Cylinder  SpinFit-vXB-z 
mag(EcyI)Anag(Esph) 

Ang  Between  Ecyl  and  Esph 
SphEy- VxB_y/IVxB_yl 
SphEz  -  VxB_z  /  IVxB_zl 
CyEy  -  VxB_y  /  IVxB_yl 
CylEz- VxB_z/IVxB_zl 


sqtt((Ey-VBy)\u2+(Ez-VBz)\u2) 

sqtt((Ey-VBy)Nu2+(Ez-VBz)\u2) 

Sph  (E,  VxB)  angle 
Cyl  (E,  VxB)  angle 
AngIe(Ymgse,  Sph-Booml) 
Angle(Ymgse,  Cyl-Booml) 
AngIe(Ymgse,  Sph-Booml) 
Angle(Ymgse,  Cyl-Booml) 

Sphere  boom  spin  time 
Cylinder  boom  spin  time 
Sphere  booml_X 
Sphere  booml_Y 
Sphere  booml_Z 
Cylinder  boom3_X 
Cylinder  boom3_Y 
Cylinder  boom3_Z 
Agmod  Spinperiod 
(Vl+V2)/2 
(BVl+BV2)/2 

(Vl+V2)/2,  (V3+V4)/2,  SC_Vel  (MGSE) 
V12,  V34,  Booml  Angle  (to  MGSE-Y) 
SoftSFofV12 
SoftSFofV34 
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Conceptual  Design  of  the  CRRES  Software 

1.  Introduction: 

It  is  the  purpose  of  this  document  to  specify  the  concepts  used  in  the  design  and  implementa¬ 
tion  of  the  CRRES  viewing  software.  It  serves  two  main  purposes 

•  It  serves  as  an  introduction  to  the  software  for  anyone  with  programming 
responsibilities  on  the  software. 

•  It  serves  as  an  initial  guide  for  anyone  who  wishes  to  write  extensions  to 
the  existing  CRRES  software. 

A  more  detailed,  implementation-level  description  of  the  software  can  be  found  in  the  docu¬ 
ment  entitled:  "Implementation  Notes  of  the  CRRES  Software". 


2.  Description  of  the  Original  Version  of  the  CRRES  Viewing  Program 

2.1  Program  Design  Constraints: 

The  original  CRRES  program  was  designed  and  implemented  in  1990, 1991  by  Jack  Vemetti, 
John  Caron,  and  Chris  Sparhawk  of  SSL  in  the  "C"  programming  language.  It  was  to  serve  the 
same  purpose  as  micro-fiche  were  to  older  data  sets  (e.g.  ISEE),  hence  the  name  "fiche".  At  the 
user's  request,  it  was  to  produce  time-series  plots  on  a  display  screen  for  selected  data  quantities, 
all  plots  over  a  common  time  period. 

The  following  were  the  major  design  considerations  of  the  original  version. 

•  The  CRRES  software  was  to  be  portable  between  Sun  UNIX  and  large  extended-memor>' 
DOS  machines. 

•  The  input  data  included  orbit-by-orbit  telemetry,  attitude,  and  ephemeris  files  supplied 

by  AFGL.  The  telemetry  and  ephemeris  files  were  binary,  defined  at  byte  level.  The  attitude 
file  was  ASCII.  These  files  were  to  be  readable  by  both  the  Sun  and  PC  versions  of  the 
program.  The  telemetry  file  was  defined  with  a  structure  very  similar  to  the  raw  agency 
format  and  included  an  appended  index  for  use  in  random  access.  It  was  not  assumed  that 
processed,  secondary  data  sets  would  be  available. 

•  The  program  was  to  be  very  flexible  with  regard  to  which  quantities,  which  time  spans,  and 
what  vertical  scaling  could  be  viewed.  A  user  could  view  up  to  32  plots  at  once  (out  of  over 
\Q0  available)  for  any  time  span  ranging  from  a  few  milliseconds  to  an  entire  orbit  (10  hours) 
with  the  vertical  scaling  independently  set  for  each  plot. 

•  Only  single  orbits  could  be  viewed  at  one  time:  there  was  no  facility  for  looking  at  time 
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spans  overlapping  two  orbits. 

•  The  program  was  to  view,  not  only  processed  data  from  agency  tapes,  but  data  from  the 
CRRES  GSE  as  well 

2.2  Program  Components: 

The  DOS  requirement  immediately  impelled  use  of  a  single,  large  program  which  would  be 
responsible  for  every  aspect  of  the  processing  (since  DOS  is  not  a  multi-tasking  OS). 

Portability  between  UNDC  and  DOS  also  precluded  direct  use  of  graphics  and  user-interface 
toolkit  standard  software  packages.  This  required  building  in-house  packages  to  handle  various 
graphics,  user-interface,  and  system-level  operations.  These  "covering"-libraries  included  both 
UNDC  and  DOS  versions  of  each  of  the  following: 

tooll  (basic  system  operations) 

toolm  (basic  mathematics  routines) 

gsh  (graphics  primitives,  both  "display"  and  "hardcopy") 

gob  (user-interface  ("graphical  objects")  routines) 

In  addition,  there  was  the  CRRES  decommutation  library: 

decom 

It  is  this  library  which  knows  how  to  decode  the  CRRES  telemetry,  ephemeris,  and  attitude 
files.  Note  that  the  AFGL  "AGMOD"  software  was  incorporated  into  "decom"  and  is  used  for 
decoding  the  attitude  files. 

The  application  source  itself  ("fiche")  includes  four  main  areas: 

fiche  (main  user-interface  controller  and  plot  generator) 

inst  (creates  instrument  (raw)  quantity  data  buffers) 

phys  (creates  derived  "physics"  quantity  buffers  from  raw  data). 

OP  (handles  "operations") 

2.3  Program  Implementation: 

The  requirement  of  supporting  DOS  recommended  an  "event-driven"  approach  to  the  software. 
Because  memory  is  so  valuable  on  the  PC  (even  8  Mbytes  of  extended-memory  is  smaller  than  a 
packed  orbit  of  non-time-tagged  CRRES  data),  it  was  not  possible  to  store  complete,  time-tagged 
arrays  of  raw  quantities  (we  assumed  that  users  would  often  request  ten  hours  of  data). 

The  alternative  was  to  perform  as  much  processing  "on-the-fly"  as  possible  when  individual 
data  points  were  returned  to  the  application  from  the  decommutator.  Thus,  a  single  raw  data  point 
would  often  be  used,  as  soon  as  it  entered  the  application,  in  5  or  10  different  physics  computa¬ 
tions.  The  raw  data  point  itself  would  not  be  stored  in  any  buffer  unless  it  was  to  be  directly  used 
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.f’  oae  '  the  displayed  plots. 

The  following  indicates  how  a  decommutation  session  within  the  program  operated: 

a.  The  program  ("fiche"  module)  tells  the  decommutator  exactly  which  types  of  data  it  is  inter¬ 
ested  in.  It  also  indicates  whether  the  decommutator  is  to  send  back  all  possible  points  of  all 
requested  data  types  or  if  it  is  to  decrease  the  data  density  of  all  returned  data  types  by  limiting 
the  number  of  points  of  each  type  to  a  positive  integer  "n"  (the  default  was  2000)  of  evenly 
spaced  points  for  any  requested  time  span.  It  is  this  data  density  control  which  allowed  plot  data 
to  be  buffered  whole,  in  reasonable  amounts,  for  operation  of  the  PC  version. 

b.  The  program  then  tells  the  decommutator  to  stan  sending  back  the  data  types  mentioned  in 
step  (a)  for  a  given  time  span.  One  of  the  arguments  to  this  subroutine  call  is  a  data-return  func¬ 
tion  pointer,  which  indicates  where  the  decommutator  is  to  send  back  the  individual  data  points. 
This  function  is  in  the  "inst"  module. 

c.  Now  the  decommutator  acts  like  the  controlling  program  which  sends  individual  data 
points  to  the  application.  This  is  what  is  meant  by  an  "event-driven"  architecture.  The  decom¬ 
mutator  acts  like  an  event-generator  (the  "events"  are  the  time-tagged  data  points),  sending  each 
data  point  to  the  application,  which  responds  in  some  way  to  those  points.  Note  that  the  decom¬ 
mutator  doesn't  care  how  the  application  uses  a  data  point. 

d.  A  single  data  point  from  the  decommutator  would  take  the  following  path  through  the 
application: 

The  data-retum  function  in  the  "inst"  module  receives  the  event  from  the 
decommutator  and  figures  out  what  type  of  data  it  is. 

The  data-retum  function  then  loops  through  all  of  the  currently  defined  plots 
and  secs  if  this  type  of  data  is  required  for  each  of  those  plots  (it  is  required  for 
at  least  one  of  them  because  of  step  (a)). 

When  a  relevant  plot  is  found,  the  data  is  scaled  and  offset  (the  scaling  and 
offset  coefficients  for  the  type  of  data  was  set  up  at  program  initialization  time). 

If  this  is  a  "raw"  instrument  plot,  the  scaled  and  offset  data  is  passed  directly  to 
the  plotting  routine  in  the  "fiche"  module,  which  inserts  the  data  into  the  buffer  for 
that  plot. 

If  this  is  a  "physics"  plot,  the  scaled  and  offset  data  is  passed  into  the  "phys"  module, 
where  it  is  routed,  via  a  complicated  switch  statement,  to  the  appropriate  code  for  use 
in  a  scientific  algorithm.  Note  that  this  will  only  sometimes  send  a  "physics"  point  to 
the  "fiche"  module  for  plotting,  but  not  always,  since  the  algorithm  may  need  more 
data  before  a  physics  plot  point  can  be  generated. 

When  all  of  the  current  plots  have  been  accessed  in  the  loop,  control  is  returned  to 
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the  decommutator  for  the  next  "event”. 

e.  When  the  decommutator  comes  to  the  end  of  the  time-span  (from  step  b),  it  sends  a  special 
"event"  to  the  "inst"  module  indicating  that  it  is  now  finished.  The  decommutator  is  exited  and 
control  is  passed  up  to  the  "fiche"  module  which  outputs  the  plots,  whose  buffers  have  been  set 
up  by  the  previous  steps,  to  the  display. 

It  should  be  noted  the  "OP"  software  acted  directly  on  currently  existing  "plot"  buffers  as 
stored  in  the  "fiche"  module.  It  was  not  dirccdy  affected  by  the  event-driven  nature  of  the  pro¬ 
gram. 

2.4  Program  Presentation: 

The  application  presented  itself  to  a  user  with  a  large  single  window  with  an  initial  list  of  pre¬ 
defined  user  "configurations"  to  select  from.  Note  that  a  configuration  includes  an  orbit  name, 
time  span  within  the  orbit,  and  a  list  of  current  plots.  When  the  user  selected  a  configuration,  the 
program  would  start  the  decommutator  for  the  given  time  span.  When  the  plot  buffers  were  com¬ 
plete,  then  the  plots  would  be  output  and  the  program  would  present  a  set  of  popup  menus  that 
allow  the  user  to  change  the  current  plot  configuration,  change  the  time  span,  create  hardcopy, 
etc. 


2.5  Program  Deficiencies: 

As  stated  above,  the  "event-driven"  nature  of  the  software  requires  that  physics  computations 
be  performed  on  the  fly  as  raw  data  points  are  returned  from  the  decommutator.  This  requires  a 
complicated  but  very  delicate  input  filter  structure  which  is  extremely  difficult  and  dangerous  to 
maintain  and  extend.  Indeed,  many  program  bugs  were  introduced  when  adding  new  "physics" 
plots  to  the  program's  repertoire.  Source  code  reuse  and  modularization  also  suffered  from  the 
use  of  this  point-by-point  filter.  Furthermore,  the  science  source  code  itself  now  has  the  respon¬ 
sibility  of  buffering  appropriate  data  points  for  use.  This  is  difficult  and  would  be  unnecessary  if 
the  raw  points  are  already  buffered,  which  would  also  allow  the  algorithm  designer  to  concentrate 
on  the  scientific  algorithm  itself. 

It  also  became  apparent  by  the  end  of  1990  that  DOS  was  an  unworkable  platform  for  this 
application  simply  from  the  standpoint  of  the  familiar  640K  DOS  main  memory  limit.  The  pro¬ 
gram  itself,  through  the  addition  of  physics  quantities,  grew  quite  large  for  a  DOS  program. 

The  extended  memory  was  usable  for  data  storage,  but  did  not  help  in  terms  of  executable  code. 
The  use  of  program  overlays  was  not  an  option  because  of  the  programmer  time  involved  in  such 
a  difficult  process. 

The  event-driven  nature  created  another  problem  with  the  program.  Since  everything  had  to 
be  generated  on  a  point-by-point  basis,  it  was  necessary  to  have  the  decommutator  restrict  its  out¬ 
put  to  only  those  quantities  required  by  the  set  of  plots  defined  by  the  user’s  configuration  at  a 
given  time.  In  this  way  much  time  was  saved  because  no  extraneous  data  would  be  sent  around 
the  program.  However,  it  also  meant  that  if  extra  plots  were  requested  later  or  the  current  time 
span  was  increased,  the  decommutator  had  to  be  called  again!  It  should  only  be  necessary  to 
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decommutatc  data  once!  This  is  a  ver\'  complicated  and  time  consuming  part  of  the  processing 
and  should  be  restricted  to  a  single  session  if  possible. 

Another  deficient  area  of  the  original  program  is  in  burst  processing.  Since  ver>  large  data 
arrays  were  not  a  viable  program  option  and  since  all  data  had  to  be  processed  on  a  point-by¬ 
point  basis,  the  fact  that  burst  data  is  played  back  significantly  later  than  actual  burst  occurrence 
made  it  very  difficult  to  insure  correct  time-appearance  of  burst  data  in  the  program  plots.  In  fact . 
some  bursts  are  played  back  in  later  orbits  than  their  actual  occurrence.  A  much  more  robust 
form  of  burst  handling  would  entail  pre-buffering  and  time-tagging  all  the  bursts  for  an  orbit 
before  any  plotting  occurs. 

Finally,  in  general,  it  is  difficult  and  dangerous  to  have  anyone  but  those  programmers  inti¬ 
mately  knowledgeable  about  the  single-program  architecture  make  additions  to  the  software. 
This  is  unacceptable  since  it  should  be  reasonably  simply  for  a  scientist,  or  anyone  else  familiar 
as  a  user  but  not  well-versed  in  the  internals  of  the  software,  to  create  useful  extensions. 


3.  Architecture  of  the  New  Version  of  the  CRRES  Viewing  program 

3.1  Constraints  of  the  New  Version; 

The  following  are  the  new  design  constraints: 

•  Only  UNIX  will  be  supported.  However,  the  software  must  be  ponable  to  a  large  class 
of  UNIX  platforms  (not  just  SUN!). 

•  The  software  will  be  optimized  for  lapge  physical  memory  machines  (at  least  64  MBytes). 

•  All  of  the  flexibility  of  the  older  version  will  be  maintained.  In  addition,  time  spans  will  no 
longer  to  be  constrained  to  be  within  a  single  orbit.  Time  spans  crossing  orbit  boundaries 
will  be  supported. 

•  The  design  will  support  easy  "connection"  to  data  sources  other  than  the  CRRES  AFGL 
agency  files.  This  includes  other  CRRES  data  file  formats  (exported  files)  or  data  from  other 
instruments  like  POLAR,  CLUSTER,  or  FAST. 

•  Scientific  extensions  to  the  software  or  entire  new  applications  must  be  easy  to  implement 
for  someone  not  versed  in  the  program  internals.  In  fact,  the  extension  capability  must 
support  both  "C"  and  "Fortran". 

•  The  software  must  also  be  designed  so  that  realtime  data  applications  (e.g.  GSH,  quick-look 
software)  can  be  easily  implemented.  In  particular,  the  FAST  project  will  need  this 
capability. 

3.2  System  Design  Considerations 
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This  section  introduces  the  concepts  that  are  of  importance  in  the  design  of  the  new  software  at 
a  high  system  level. 

3.2.1  Single'Program  vrs.  Object  Oriented: 

In  order  to  confront  the  deficiencies  of  the  original  version,  and  consider  the  new  design  con¬ 
straints  above,  it  is  useful  to  look  at  the  general  programming  paradigms  that  are  available. 

Single-Program: 

The  original  version,  as  stated,  was  written  as  single,  procedural  program.  It  is  well  known  in 
the  software  world  that  large,  single-  architecture  programs  invariably  become  nightmarish  in 
terms  of  maintainability  and  extensibility.  It  is  inevitable  that  as  a  program  grows  in  size,  the 
number  of  internal,  module-by-module  dependencies  increase.  At  the  same  time  program  docu¬ 
mentation  falls  behind.  New  programmers  on  an  application  find  that  they  must  spend  very 
large  amounts  of  time  just  learning  where  various  sub-tasks  within  the  program  are  actually  per¬ 
formed.  Adding  extensions  require  very  delicate  and  dangerous  alterations  of  the  inter-module 
interfaces.  It  is  rare,  when  such  changes  are  made,  that  there  is  enough  time  for  complete  re-test¬ 
ing. 

Object-Oriented: 

The  new  paradigm  (and  it  has  become  something  of  an  industry  buzzword)  is  "object-oriented" 
programming.  There  are  many  descriptions  of  this  term  in  the  literature  but  the  important  con¬ 
cept  with  regard  to  this  software  is  to  create  separate  programs  which  perform  relatively  small 
and  well-defined  tasks.  Of  course,  it  is  imperative  that  these  individual  programs  communicate 
with  each  other  using  well-specified  protocols  on  a  common  inter-program  communication  sys¬ 
tem  in  order  to  cooperate  in  performing  useful,  large-scale  applications.  This  requires  a  robust 
and  sophisticated  operating  system. 

There  are  two  immediate  benefits  to  using  the  "object-oriented"  paradigm.  Since  each  pro¬ 
gram  has  a  very  specialized  responsibility,  it  is  much  easier  to  design,  code,  and  test  than  a  large 
single-architecture  program.  Secondly,  since  the  programs  are  designed  to  perform  specialized 
tasks  independent  of  a  specific  application,  they  are  reusable  (i.c.  they  can  be  used  in  more  than 
a  single  application). 

A  major  caveat  when  designing  an  object-oriented  system  is  that  decisions  must  be  made  as  to 
the  level  of  decomposition  of  tasks  into  separate  programs.  Too  many  very  small  and  simple 
programs  would  use  an  inordinate  amount  of  inter-process  communication,  reducing  program 
responsiveness. 

The  typical  object-oriented  model  is  called  "client/server".  A  "server"  is  a  program  which  per¬ 
forms  a  task  requested  by  another  program  (called  the  "client"  program).  Note  that  a  program 
can  be  a  client  to  one  program  and  a  server  to  another. 
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In  order  to  meet  the  design  constraints  in  section  3.1,  it  is  clear  that  the  refurbished  CRRE^ 
program  should  be  designed  in  the  object-oriented  way.  Since  only  U.NIX  now  need  be  sup 
ported  by  the  software,  this  is  can  be  done.  UNIX  supports  all  of  the  inter -process  coniinunica 
tions  (IPC)  requirements  for  the  object-oriented  paradigm. 

3.2,2  Use  of  Large  Data  Buffers: 

As  stated  in  the  descripbon  of  the  original  version  of  the  program,  the  "on-the-fly"  technique;, 
used  in  the  scientific  quantity  computations  were  very  troublesome.  The  more  traditional 
approach  is  to  delay  computation  of  derived  quantities  until  me  entire  data  set  of  the  "raw"  qua  i- 
tities  are  easily  accessible  as  arrays  in  memory.  Availability  of  these  raw  data  arrays  greatly  sim¬ 
plify  the  design,  coding,  and  testing  of  the  scientific  algorithms. 

The  new  version  of  the  CRRES  software  will  be  designed  to  make  use  of  large  data  arrays. 
That  is  why  large  memory  machines  are  considered  as  an  essential  requirement  in  section  3.1. 

Data  buffers  are  to  be  used  in  the  following  way:  The  application  will  request  the  data  for  a 
given  time-span  from  the  decommutator.  The  decommutator  will  then  buffer  all  of  the  data  for 
the  time-span  in  the  appropriate  arrays  (one  array  for  each  data  quantity  type,  with  individual 
points  stored  in  time-increasing  sequence).  When  the  decommutator  finishes  the  time  span,  the 
requested  science  algorithms  will  be  invoked,  using  the  raw  data  buffers  as  input.  They  will  pro¬ 
duce  data  array  buffers  of  their  own,  which  will  then  be  plotted. 

3.2J  Use  of  Shared-Memory  and  Memory-Mapped  Files: 

The  new  design  envisions  use  of  specialized  and  separate  programs,  as  well  as  large  data  arrays 
in  memory.  This  requires  a  method  of  sharing  data  buffers  between  different  concurrent  pro¬ 
grams. 

The  UNIX  operating  system  on  the  Sun  supports  two  methods  of  sharing  data  arrays  between 
programs:  "shared-memory"  and  "memory-mapped  files". 

Shared-Memory: 

Shared-memory  is  a  standard  UNIX  System  V  mechanism  which  allows  one  program  to  grab 
control  of  a  segment  of  UNIX  virtual  memory.  Other  programs  may  then  request  access  to  this 
memory  segment.  UNIX  "semaphores"  (another  System  V  feature)  can  be  used  to  synchronize 
requests  for  reads  and  writes  to  this  memory  between  programs. 

One  disadvantage  in  the  use  of  shared-memory  is  that  standard  UNIX  configurations  only  sup¬ 
port  shared-memory  "segments"  of  1  Mbyte  or  less  (although  100  or  more  "segments '  are  allowed 
at  one  time).  This  is  an  important  limitation  because  CRRES  VI 2,  V34,  and  raw  mag-field  data, 
for  one  orbit,  will  each  require  5  to  10  Mbyte  segments.  It  is  not  acceptable  to  split  a  data  quan¬ 
tity  buffer  among  several  segments  -  this  will  not  allow  simple,  array-indexing  into  the  buffer  by 
an  application.  This  limitation  is  easy  to  fix  (we  have  done  so  on  our  own  machines)  but  it 
requires  re-configuring  the  UNIX  kernel.  This  will  slightly  increase  the  difficulty  of  suppon  to 
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non-SSL  users  of  the  CRRES  software. 

Memory-Mapped  Files: 

This  option  is  available  on  Sun  and  many  other  UNIX  platforms,  but  is  not  a  standard  System 
V  mechanism.  The  main  advantage  of  this  mechanism  over  shared-memoiy  is  that  it  does  not 
require  a  UNIX  kernel  re-configuration.  It  does,  however,  require  backing-store  disk  space 
(since  mapped-memory  is  considered  an  extension  of  the  basic  system  virtual  memory).  For  an 
entire  CRRES  orbit,  this  would  require  40  Mbytes  of  free  disk  space  on  the  local  machine  for  a 
margin  of  safety. 

Provision  for  support  of  both  methods  will  be  implemented  into  the  new  version  of  the  applica¬ 
tion.  This  will  allow  users  to  run  the  software  as  best  suits  their  working  environment. 

3.2.4  Use  of  InterProcess  Communications: 

Since  the  CRRES  software  will  be  split  into  a  number  of  different  programs,  it  will  be  neces¬ 
sary  to  provide  a  message/request  transport  mechanism  for  sending  information  and  commands 
between  the  programs.  Note  that  this  will  not  be  used  for  actual  science  data  transmission  (which 
is  handled  by  use  of  shared-memory  or  memory-mapped  files)  except  in  the  case  where  the 
CRRES  decommutator  is  explicitly  requested  to  use  "streaming”-mode  (described  in  section  3.3 
of  this  document).  The  standard  CRRES  software  will  not  use  streaming  mode. 

Since  UNIX  provides  many  forms  of  InterProcess  Communications  (hereby  referred  to  as 
"IPC"),  a  decision  had  to  be  made  as  to  what  form  to  use.  It  is  very  tempting  to  use  SUN’s  high- 
level  RPC  (Remote  Procedure  Call)  mechanism  because  of  ease  of  use.  However,  this  is  not  a 
standard  UNIX  mechanism,  although  it  is  supported  on  a  number  of  other  UNIX  platforms.  The 
highest  level  of  IPC  protocol  supponed  on  almost  all  UNIX  platforms  is  TCP/IP.  It  is  this  proto¬ 
col  that  will  be  used  in  the  CRRES  software.  This  provides  adequate  support  for  communications 
between  programs  running  on  the  same  machine  as  well  as  between  programs  running  on  separate 
machines  on  a  network.  Use  of  TCP/IP  in  the  CRRES  program  will  be  through  a  UCB-designed 
library  specializing  in  the  IPC  needs  of  the  software. 

TCP/IP  is  a  protocol,  not  a  transmission  mechanism.  There  are  two  possible  transport  mecha¬ 
nisms  on  UNIX:  Berkeley  (BSD)  sockets  and  SystemV’s  Transport  Layer  Interface  (TTI).  TLI  is 
supposed  to  become  the  UNIX  standard  IPC  transport  mechanism.  However,  almost  all  network 
programming  is  currently  done  using  BSD  sockets.  We  will  use  BSD  sockets  with  the  intention 
of  writing  a  TLI  version  of  the  IPC  library  later. 

3.3  Overview  of  the  Software  Design: 

This  section  will  describe  the  main  components  of  the  CRRES  program. 

The  new  CRRES  software  will  take  advantage  of  the  UNIX  InterProcess  Communication 
(IPC)  capability  and  split  the  software  into  distinct  programs,  with  well-defined  interfaces.  The 
main  programs  in  the  CRRES  software  will  be: 
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•  User  Interface  Module  (UI) 

•  CRRES  Decommutation  Module 

•  Science  Control  Module  and  separate  science  programs  (SCM) 

•  File  Export  and  Import  Facilities 

•  Data  Quantity  Handler  Module  (DQH) 

There  will  be  several  other  subsidiary  programs  which  need  not  be  discussed  at  this  conceptual 
level.  TTiey  will  be  described  in  the  Implementation  Document 

Here  is  a  brief  description  of  the  main  programs: 

3.3.1  User  Interface  Module. 

This  program  will  handle  interactive  user-control  of  the  software.  It  is  from  this  program  that 
time-spans  for  viewing  are  set,  plots  are  added/deleted  from  the  current  viewing  configuration, 
hard  copy  is  output,  etc.  It  will  be  mouse  and  menu-driven.  It  is  also  responsible  for  producing 
plot  output  to  a  display  or  hardcopy  device. 

3.3.2  CRRES  Decommutation  Module: 

This  program  decodes  CRRES  data  files  (telemetry,  attitude,  and  ephemeris)  and  provides  the 
time-tagged,  decoded  data  to  other  programs.  It  also  has  the  responsibility  of  informing  other 
programs  in  the  overall  software  as  to  the  names  and  attributes  of  the  data  produced  by  the 
CRRES  instrument. 

3.3.3  Science  Control  Module  and  customized  science  programs: 

The  science-algorithm  portion  of  the  software  is  constructed  to  allow  science  application  pro¬ 
grammers  easy  access  into  the  application.  It  is  envisioned  that  separate,  customized  programs 
will  be  written,  following  the  standard  conventions  (from  the  "Implementation  Document"),  and 
connected  to  a  single,  controlling  program  called  the  "Science  Control  Module".  This  program 
has  the  responsibility  of  ensuring  access  by  the  science  sub-programs  to  the  appropriate  data 
buffers  controlled  by  the  Data  Quantity  Handler,  and  communicating  the  data  produced  by  the 
sub-programs  to  the  User  Interface  for  plotting.  There  will  be  a  standard  science  package  which 
computes  all  of  the  derived  quantities  of  the  original  version  of  the  program,  as  well  as  the  "oper¬ 
ator"  commands. 

3.3.4  File  Export  and  Import  Facilities: 

The  ability  to  input  and  output  a  variety  of  data  files  is  crucial  to  the  ongoing  utility  of  this  soft¬ 
ware.  Hence,  the  new  version  of  the  CRRES  "Fiche"  software  will  provide  facilities  for  file 
export  and  file  impon  of  ASCII  files,  flat  files,  the  CDF  format  files,  and  CRRES  data  format  files 
which  will  enable  users  to  generate  plottable  data  to  a  fiJe  and  recall  it  quickly. 

The  export  and  import  facilities  will  be  provided  in  two  modes.  The  user  interface  mode  will 
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allow  the  user  to  export  and  import  files  while  he/she  waits.  The  batch  mode  will  allow  the  user 
to  run  the  software  over-night  or  at  a  convenient  down  time.  This  will  be  useful  for  longer  execu¬ 
tions  and  computations. 

Some  of  the  file  formats  listed  above  are  not  intended  to  be  supponed  in  the  primary  develop¬ 
ment  schedule.  These  will  however  be  included  in  the  secondary  development  effort. 

3.3.5  Data  Quantity  Handler  Module. 

This  program  maintains  the  list  of  all  current  quantity  buffers  for  access  by  the  other  modules  of 
the  CURES  software  system.  Note  that  these  buffers  will  be  generated  by  this  program  as  either 
shared-memory  or  mapped-memory  files.  Note  also  that  the  module  is  capable  of  handling  input 
sources  other  than  just  the  CRRES  decommutator  and  Science  module.  It  is  conceivable  that,  at  a 
given  instant,  it  may  be  handling  data  from  two  separate  spacecraft  which  would  allow  an  applica¬ 
tion  communicating  with  it  to  compare  the  data  from  the  two  instruments  in  some  way. 

3.4  Data  Flow  Description: 

This  section  provides  a  summary  of  the  data  flow  between  the  programs  described  in  the  previ¬ 
ous  section. 

There  are  four  main  categories  of  "data"  which  need  to  be  considered  conceptually,  where 
"data"  means  any  information  flowing  between  programs.  They  are: 

•  Commands  and  requests  for  service  from  one  program  to  another 

•  Quantity  Description  information 

•  Memory  buffer  pointers 

•  Data  in  the  usual  sense  (telemetry,  attitude,  ephemeris) 

The  description  of  commands  and  requests  is  very  detailed  and  best  left  for  the  "Implementa¬ 
tion  Document".  It  suffices  to  mention  at  this  level  that  these  commands  are  used  mostly  to  trig¬ 
ger  the  flow  of  the  other  three  types  of  information  between  the  appropriate  programs. 

Quantity  descriptors  exist  as  a  mechanism  to  break  any  dependence  that  the  UI,  DQH,  and 
SCM  would  normally  have  on  the  specifics  of  CRRES  data.  By  their  use,  the  UI  can  be  written 
with  no  pre-knowledge  of  the  CRRES  data  set,  the  DQH  will  work  with  the  data  for  any  instru¬ 
ment  (at  least  in  the  POLAR,  CLUSTER,  FAST  series),  and  the  science  programs  can  be  written 
with  no  need  to  know  the  internals  of  the  CRRES  decommutator  and  its  associated  data  types. 
They  are  defined  in  detail  in  the  "Implementation  Document".  These  descriptors  are  passed 
between  the  following  pairs: 

CRRES  Decom  to  DQH  (raw  data  quantity  descriptors  -  piece-meal  as  buffers  are  requested) 
SCM  to  DQH  (quantity  descriptors  defined  by  any  of  the  science  plug-in  modules  - 
piece-meal  as  buffers  arc  requested) 

CRRES  Decom  to  UI  (raw  data  quantity  descriptors) 

SCM  to  UI  (quantity  descriptors  defined  by  any  of  the  science  plug-in  modules) 
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Memory  buffer  pointers  are  maintained  by  the  E>QH  and  are  used  by  the  UI  to  set  plot  data 
arrays  and  by  the  SCM  and  science  programs  for  raw  data  array  access.  Here  are  the  interprogram 
paths  for  transmission  of  memory  buffer  locations; 

SCM  to  UI 
Decommutator  to  UI 

Note  that  the  raw  data  is  never  sent  directly  out  of  the  decommutator.  The  DQH  informs  it  as 
to  the  location  of  the  appropriate  raw  data  buffers,  which  Decom  fills  as  it  decodes.  These  buffers 
are  then  made  available  to  the  Science  modules  and  User  Interface  by  the  Decommutator. 

The  following  diagram  summarizes  the  major  data  flow  of  the  software: 
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The  following  section  describes  the  main  programs  in  more  detail. 


4.  Internal  Structure  of  the  Major  Software  Modules. 

This  section  describes  the  internal  structure  of  each  of  the  major  programs  in  the  software  sys¬ 
tem.  Specific  subroutine  descriptions  and  interface  protocols  are  left  to  the  "Implementation  Doc¬ 
ument”. 

4.1  User  Interface  Module: 
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The  User  Interface  Module’s  purpose  will  be  simply  to  provide  the  user  with  facilities  to  input 
a  series  of  requests  to  external  data  sources  for  data  and  to  provide  a  convenient  interface  for 
maiiipulating  that  data  for  display.  This  interface  will  be  completely  generic  in  that  none  of  the 
internal  menus  will  be  instrument  dependent.  The  User  Interface  Module  will  contain  neither 
instrument  (satellite,  rocket,  file,  etc.)  specific  operations  nor  any  data  computational  :'unctlon^. 

In  the  "Fiche"  application  the  "Fiche"  User  Interface  Module  will  be  provided  with  data  from 
both  the  CRRES  Science  Algorithm  Module  and  the  CRRES  Raw  Data  Source.  These  three  pro 
grams  will  “attach”  together  and  act  in  unison  to  provide  the  full,  extant  facilities  of  the  "Fiche 
Program". 


User  Interface  Routines 
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The  process  of  linking  up  will  occur  something  like  this.  The  CRRES  Science  .Algorithm 
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Module  will  attach  to  the  "Fiche"  User  Interface,  identify  itself  and  pass  to  the  User  Interface  a  list 
of  data  which  the  CRRES  Science  Algorithm  Module  can  make  available  upon  request.  The 
CRRES  Raw  Data  (Decommutator)  Module  will  do  the  same.  These  two  programs  will  be 
referred  to  as  “Sources”. 

When  the  User  Interface  Module  passes  a  request  for  a  certain  data  quantity  (using  the  list  of 
available  plots  for  that  Source  which  was  passed  to  it  on  anachment)  to  the  appropriate  Source, 
the  Source  will  immediately  send  back  all  information  the  plotting  routine  will  need  to  set  up  the 
plot  frame.  The  Source  will  then  obtain  or  create  the  data  buffers  required  for  the  requested  quan¬ 
tity  and  will  return  the  data  to  the  User  Interface  Module  via  the  DQH  data  buffers  asynchro¬ 
nously  as  it  becomes  available.  The  User  Interface  Module  will  plot  this  data  as  it  is  received  in  a 
real-time  fashion. 

At  this  time  we  should  mention  that  the  actual  redesign  of  the  User  Interface  Module  is  some¬ 
what  in  question  due  to  possible  time  constraints.  The  User  Interface  Module,  as  it  stands  now,  is 
not  well  suited  to  fit  in  with  the  concept  of  breaking  the  “Fiche”  software  apart  into  separate  exe¬ 
cutable  portions.  The  redesign  to  allow  the  User  Interface  Module  to  take  full  advantage  of  the 
new  software  structure  could  be  quite  time  consuming  depending  on  the  level  of  reconstruction 
which  is  undertaken.  Several  possibilities  exist.  The  quickest  solution  would  be  to  simply  split  the 
existing  User  Interface  off  into  its  own  executable  package  and  stick  the  interprocess  communica¬ 
tions  on  to  it  as  an  appendage.  A  very  basic,  but  functional.  User  Interface  could  be  built  in  a  rela¬ 
tively  short  period  of  time,  but  this  would  leave  the  User  Interface  disorganized  and 
unmanageable  for  future  modifications.  This  is  not  the  optimal  solution.  The  optimal  solution 
would  be  to  completely  redesign  the  User  Interface  to  use  the  advantages  gained  by  splitting  the 
software  and  to  build  it  either  on  the  existing  libraries  which  are  semi-portable  or  on  a  standard 
library  (MOTIF  or  OpenLook).  This  option  might  take  only  marginally  longer. 

Again,  this  is  a  consideration  based  on  available  time.  We  will,  however,  proceed  with  this  sec¬ 
tion  as  if  this  were  the  path  we  would  pursue.  The  goals  and  functionality  of  the  User  Interface 
Module  discussed  in  the  above  paragraphs  will  be  met  in  the  redesigned  version  by  breaking  the 
User  Interface  Module  down  into  several  functional  components  which  will  work  together  to 
accomplish  the  set  goals.  These  functional  components  are  listed  below  and  will  be  discussed  in 
detail  in  the  appropriate  section. 

4.1.1.  User/Source  Interface 

4. 1 .2.  Incoming  Data  Parse  and  Direct 

4. 1 .3.  Outgoing  Data  Pack  and  Direct 

4. 1 .4.  Data  Poll  and  Collect 

4.1.5.  User  Interface 

4.1.6.  Plotter 

4.1.1.  User/Source  Interface 

The  User/Source  Interface  wiU  be  a  connection  which  will  be  used  to  send  small  amounts  of 
data  between  what  is  known  as  a  "source",  a  provider  of  plottable  information,  and  what  is  known 
as  a  "user",  a  process  which  utilizes  the  data  for  some  sort  of  user  output.  Basic  sorts  of  messages 
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^vhich  will  be  sent  from  the  User  to  the  Source  will  include  information  the  Source  requires  from 
the  user  to  operate  correctly  and  requests  for  plot  information/data.  The  sorts  of  messages  w  hicn 
will  be  sent  ftom  the  Source  back  to  the  User  will  include  an  initiation  list  of  quantities  available 
from  the  Source  and  a  Source  name.  Specific  Plot  information,  and  the  asynchronous  plottable 
data  itself.  The  latter  will  comprise  the  majority  of  information  transferred  via  this  interface 


4.12.  Incoming  Data  Parse  and  Direct 

The  Incoming  Data  Parse  and  Direct  Module  will  be  responsible  for  receiving  all  input  from  .;'I 
of  the  attached  sources.  This  routine  will  then  decode  the  input  and  pass  this  off  to  the  appropriate 
portion  of  the  User  Interface.  Data  Poll  and  Collect,  and  Plotter.  The  types  of  incoming  data  will 
include  the  Source  name,  list  of  available  plots,  and  the  Source’s  needs,  plot  information,  and  plot 
data. 


4.1.3.  Outgoing  Data  Pack  and  Direct 

The  Outgoing  Data  Pack  and  Direct  Module  will  be  responsible  for  packing  up  all  of  the  out¬ 
going  messages  and  data  into  the  appropriate  format  and  sending  them  to  the  correct  Source.  The 
ty’pes  of  outgoing  elements  this  routine  will  handle  will  include  needed  data  from  the  User  Inter¬ 
face  for  the  Sources  and  plot  requests. 

4.1.4.  Data  Poll  and  Collect 

The  Data  Poll  and  Collect  Routine  receives  the  buffer  information  originating  from  a  data 
Source  from  the  Incoming  Data  Parse  and  Direct  Routine.  It  then  uses  this  buffer  information  to 
poll  the  data  acquisition  of  the  source  and,  at  defined  intervals,  update  the  plots  in  real-time.  This 
routine  may  also  be  responsible  for  building  the  actual  plottable  buffers  from  the  DQH  data  buff¬ 
ers  for  use  by  the  plot  routines. 

4.1.5.  User  Interface 

The  User  Interface  Routines  along  with  the  Plotter  Module  are  the  most  important  (and  largest) 
portions  of  the  User  Interface  Module.  The  User  Interface  Routine  will  provide  the  user  an  envi¬ 
ronment  for  inputting  different  types  of  data  and  data  requests.  An  Environment  Manager  Routine 
will  control  what  the  user  sees  and  what  data  being  input  does  to  the  displays.  Tlie  Menu  Manage, 
will  provide  the  Environment  Manager  with  its  needed  menus  to  prompt  the  user  for  input  Finally 
the  Input  Processor  will  receive  input  and  take  the  appropriate  actions.  Each  of  these  separate 
functions  is  discussed  below. 

4.I.5.I.  Environment  Manager 

The  Environment  Manager  is  responsible  for  what  the  user  sees  in  the  menu  area,  what  menus 
are  displayed,  moving  up  and  down  the  menu  structure  and  keeping  track  of  what  inputs  corre¬ 
spond  to  what  input  areas  on  the  menu  list.  When  the  program  is  staned  the  Environment  Man- 
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ager  will  display  a  start-up  screen  (logo  type  thing),  a  list  of  available  Sources  and  a  list  of  options 
such  as  select  a  configuration,  enter  the  needs  of  the  Sources,  start  building  a  new  configuration, 
etc.  As  the  user  makes  selections  the  Environment  Manager  will  adjust  the  display  by  requesting  a 
menu  from  the  Menu  Manager  and  using  the  returned  menu  to  prompt  further  user  input.  As  any 
input  is  necessaiy  the  Environment  Manager  will  prompt  the  user,  get  this  input  and  pass  this  on 
to  the  Input  Processor.  When  a  string  of  menu  selections  leads  to  a  specific  command,  the  Envi¬ 
ronment  Manager  will  pass  this  on  to  the  Input  Processor. 

4. 1.5.2.  Menu  Manager 

The  Menu  Manager  will  read  an  ASCII  file  which  contains  a  predetermined  menu  structure.  It 
will  maintain  this  by  adding  and  deleting  from  it  modified  values  that  are  received  from  the 
attached  Sources.  For  example,  when  the  program  begins  no  Sources  or  associated  available  plots 
will  be  listed.  When  the  Sources  attach,  they  will  pass  the  Menu  Manager  through  the  User/ 
Source  Interface  and  Incoming  Data  Parse  and  Direct  Module  their  name  and  list  of  available 
plots  (e.g.  CRRES  Science  Algorithms,  Bmgse/Bgse/and  so  on).  The  Menu  Manager  will  add  the 
name  (CRRES  Science  Algorithms)  to  the  available  source  menu  selection  and  the  list  of  plots 
(Bmgse,  Bgse,  and  so  on)  to  the  available  plot  list.  Thus,  no  instrument  dependent  information 
will  need  to  reside  in  the  actual  User  Interface  Module.  When  a  request  for  a  menu  is  received 
from  the  Environment  Manager,  the  Menu  Manager  will  dynamically  create  a  menu  structure  and 
return  it  to  the  Environment  Manager.  If  a  need  request  is  received  from  a  Source  the  Menu  Man¬ 
ager  will  queue  this  up  and  at  the  next  request  for  a  menu  will  provide  a  menu  for  input  of  the 
need  first  then  the  requested  menu. 

4. 1.5.3.  Input  Processor 

The  Input  Processor  will  be  responsible  for  receiving  completed  input  or  commands  from  the 
Environment  Manager  and  directing  them  to  the  correct  place.  The  received  inputs  and  commands 
will  include  Plot  additions  and  deletions,  display  commands  such  as  panning  and  zooming  and 
Need  data  for  Sources.  When  the  Input  Processor  receives  any  plot  additions,  deletions,  or  Need 
data  for  Sources  it  will  pass  these  out  to  the  Outgoing  Data  Pack  and  Direct  Module  to  send  out  to 
the  appropriate  Source.  In  addition  it  will  send  any  display  commands  or  deletion  requests  to  the 
Plotter  Module. 


4.1.6.  Plotter 

The  Plotter  is  responsible  for  all  plot  panel  display  of  data.  It  is  only  a  receiver  of  data  pro¬ 
grammatically  speaking;  it  docs  not  send  any  data  to  any  external  process.  It  receives  incoming 
plot  information  and  data  from  Sources  and  delete  and  display  commands  from  the  User  Interface 
routines.  This  data  is  processed  by  six  routines  which  comprise  the  Plotter  Module.  A  discussion 
of  these  follows. 

4.I.6.I.  Plot  Manager 

The  Plot  Manager  simply  maintains  a  list  of  the  plots  which  are  being  displayed  and  the  param- 
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eters  which  determine  the  status  of  the  display  (plots  per  page,  displayed  umespan,  data  timespan. 
and  so  on).  This  information  corresponds  identically  with  what  is  called  the  ConfigiTation.  When 
a  set  of  Plot  Information  is  received,  the  Plot  Manager  adds  this  plot  to  its  plot  list  atid  calls  the 
Plot  Information  Routine  to  put  up  this  new  plot.  When  a  delete  command  is  receiveel  from  tlit 
User  Interface,  the  plot  is  deleted  from  its  list.  The  maintained  list  is  used  by  the  Plot  Data  Rou¬ 
tine  to  determine  which  plot  panel  incoming  data  belongs  to  and  by  the  Plot  Page  Routine  to 
determine  which  panels  to  create  plots  for. 

4. 1.6.2.  Plot  Information 

The  Plot  Information  Routine  is  responsible  for  establishing  a  plot  panels  existence.  It  plots  no 
data.  The  Plot  Information  Routine  goes  to  the  plot  list  maintained  by  the  Plot  Manager  and  gets 
the  appropriate  information  (title,  scales,  labels,  limits,  messages,  etc.).  It  then  uses  a  set  of  library 
routines  to  create  the  actual  panel  frame,  put  the  title  up,  label  the  plot,  and  establish  values  for  the 
scale. 

4. 1.6.3.  Plot  Data 

The  Plot  Data  Routine  is  responsible  for  collecting  incoming  data  and  placing  this  data  in  two 
places,  the  panel  of  the  appropriate  plot  and  a  contiguous  data  buffer.  The  Plot  Data  Routine  will 
receive  an  amount  of  data  and  will  plot  this  data  asynchronously  and  immediately  on  the  panel, 
lliis  will  allow  the  user  to  view  real-time  the  data  as  it  is  created.  The  Plot  Data  Routine  will  cre¬ 
ate  and  maintain  contiguous  buffers  for  this  plottable  data.  These  buffers  will  be  used  for  redraw¬ 
ing  the  plots  when  zooming  out  or  paging  up  and  down. 

4. 1.6.4.  Plot  Page 

The  Plot  Page  Routine  will  be  responsible  for  creating  a  fresh  page  of  plot  panels.  It  will  do 
this  by  First  clearing  the  plot  area  and  calling  a  set  of  library  routines  to  place  the  plot  title  at  the 
top  of  the  page  and  the  legend  on  the  bottom  and  any  other  pertinent  information.  1;  w  ill  then 
determine  which  plots  will  be  on  the  given  page  as  indicated  by  the  number  of  p]o*s  per  page  and 
number  of  plots  requested.  It  will  loop  through  these  and  call  Plot  Information  and  5"lot  Data  for 
each  one  to  create  that  plot  panel. 

4. 1.6.5.  Command  Processor 

The  Command  Processor  will  be  responsible  for  receiving,  parsing,  and  executing  of  com¬ 
mands  from  the  User  Interface  Routine.  The  types  of  commands  this  will  include  are  plot  delete 
requests,  zoom  and  pan  requests,  changing  the  number  of  plots  per  page,  and  so  on.  When  the 
Command  Processor  receives  one  of  these  commands  it  will  call  the  necessary  abov  e  routines  to 
appropriately  execute  the  given  command  (e.g.  Delete  Plot  -  call  Plot  Manager  to  delete  from  list 
and  call  Plot  Page  Routine  to  refresh  without  deleted  plot). 


This  is  the  breakdown  of  the  design  for  the  User  Interface  Module.  It  is  belif  ved  ibai  this 
design  will  not  only  provide  all  the  desired  performance  and  functions  required  of  the  User  ’nter- 
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face,  but  will  provide  flexibility  and  organization  for  expansion  and  refinement  in  the  future. 


4.2  CRRES  Decommutation  Module: 

The  design  of  the  CRRES  decom  program  will  establish  a  standard  data  "connection"  mecha¬ 
nism  which  the  later  projects  (POLAR,  CLUSTER,  and  FAST)  can  utilize  to  directly  hook  into 
the  new  version  of  the  CRRES  program.  This  standard  will  be  described  in  technical  detail  in  the 
"Implementation  Document".  What  follows  here  is  a  more  general  description  of  the  design  fea¬ 
tures  of  the  CRRES  decommutator. 


4.2.1  The  Decommutator  in  the  Original  CRRES  Program: 

The  original  program  included  the  decommutator  as  a  "C" -callable  library,  an  architecture 
which  precluded  use  of  other  data  streams  (from  other  instruments  or  other  CRRES  data  files). 
This  created  an  undesirable  dependency  between  the  higher  levels  of  the  program  and  the  CRRES 
decommutator  output  itself,  which  must  be  avoided  in  the  new  version.  However,  the  basic 
telemetry  decoding  algorithm  will  remain  intact  in  the  new  version. 

4.2.2  Input  Files: 

The  basic  input  files  to  the  new  CRRES  decommutator  are  the  following: 

Telemetry  file 
Attitude  file 
Ephemeris  file 
Quantity  Descriptor  file 

The  first  three  are  the  data  inputs  into  the  original  version  of  the  program  and  are  available  on 
an  orbit-by-orbit  basis  from  AFGL.  The  attitude  and  ephemeris  files  arc  exactly  as  produced  by 
AFLG  whereas  the  telemetry  file  has  an  appended  index  to  aid  in  random  accessing.  The  attitude 
file  is  ASCII  and  the  telemetry  and  ephemeris  files  are  binary. 

The  Quantity  Descriptor  file  is  a  new  ASCII  file  which  will  describe  the  types  of  instrument 
data  which  this  decommutator  provides,  as  well  as  the  scaling  and  offset  coefficients  for  those 
quantities. 

4.2.3  Modes  of  Operation: 

This  decommutator  is  called  as  a  service  by  anyone  requesting  CRRES  data  from  the  data  files 
used  by  the  original  version.  It  is  in  charge  of  decoding  CRRES  telemetry  for  given  date/time 
intervals  as  well  as  providing  spacecraft  attitude  and  ephemeris  information  for  that  same  time 
span.  Since  the  decommutator  must  be  able  to  service  many  applications,  it  must  support  two  dif¬ 
ferent  modes  of  operation:  "buffered  mode"  and  "streaming  mode". 
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Buffered  Mode: 


Buffeied  mode  will  be  the  operational  mode  of  the  new  CRRES  software.  In  this  mode,  the 
decommutator  will  not  send  data  back  to  the  client.  Instead,  the  DQH  will  transmit  the  locations 
of  the  memory  buffers  for  each  raw  data  quantity  to  the  decommutator  which  it  then  fills  as  it 
decodes  the  data  for  a  given  time  span.  The  client  will  query  the  Decommutator  for  data  and  the 
Decommutator  will  ask  the  DQH  for  pointers  to  these  arrays.  These  pointers  will  be  returned  to 
the  client  and  the  client  can  then  access  the  buffers  directly.  Note  that  the  DQH  will  define  the 
memory  arrays  as  either  shared-memory  or  memory-mapped  files,  depending  on  the  needs  of  tiie 
application. 

The  following  diagram  indicates  the  basic  data  flow  in  buffered  mode: 


Note  that  the  Application  uses  the  Quantity  Descriptors  to  set  up  its  list  of  available  plots. 
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Streaming  Mode: 

Streaming  mode  will  be  most  useful  for  quick-look,  realtime  GSE  software.  In  this  mode,  the 
decommutator  does  send  data  directly  to  the  client  application  which  would  probably  plot  the  data 
p)oints  as  soon  as  they  are  received.  Note  that  attempts  to  write  science  analysis  software  in  this 
mode  would  be  open  to  the  difficulties  which  burdened  the  original  program  (whose  decommu¬ 
tator  did  use  the  streaming  mode).  The  following  diagram  indicates  the  data  flow; 


4.2.4  Sub-modules  of  the  CRRES  Decommutator: 

The  following  are  the  sub-modules  of  the  Decommutator; 

•  InterProccss  Communications  Handler 

•  Command/Request  Inteipreter 

•  Data  Output  Handler 

•  Quantity  Descriptor  Handler 

•  Telemetry  Decoder 

•  Attitude  Decoder 

•  Ephemeris  Decoder 

The  Interprocess  Communications  Handler  (IPC  Handler)  will  be  provided  as  a  standard  library 
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.)i  C  .inu  Fortran  callable  subroutines  which  read  and  output  to  the  L'NtA  IPC  mccu.;ri.-,ni  u  ,.u 
by  the  CRRES  software  (TCP/IP  transported  by  BSD  sockets).  TTiis  library  will  be  used  by  al! 
programs  and  sub-modules  in  the  CRRES  application.  It  does  nothing  more  than  read  and  outpai 
incoming  and  outgoing  IPC  transmissions. 

The  Command/Request  Interpreter  unpacks  and  parses  incoming  IPC  messages  foi  comma,!  ], 
request  input.  Once  a  command  has  been  parsed,  the  submodule  passes  control  to  'he  ippropnaic 
subroutine  within  the  decommutator. 

The  Data  Output  Handler  packages  outgoing  data  points  and  sends  them  to  tiie  IPC  handler  for 
transmission  to  another  program.  Note  that  the  decommutator  sends  data  to  odier  processes  using 
IPC  only  in  streaming  mode. 

The  Quantity  Descriptor  Handler  reads  the  Quantity  Descriptor  file  and,  if  so  requested,  pack¬ 
ages  the  information  and  sends  it  to  the  IPC  Handler  for  transmission. 

The  above  submodules  are  really  quite  independent  of  the  CRRES  data  stream  itself  and  thereby 
form  a  reusable  subset  of  this  particular  decommutator  for  application  in  POL.XR.  CLUSTER, 
and  FAST.  The  following  submodules  are  CRRES  dependent  and  will  be  composed  for  the  most 
part  by  the  current  decommutator. 

The  Telemetry  Decoder  unpacks  and  interprets  the  Telemetry  files,  sending  data  out  on  a  point- 
by-point  basis,  for  a  pre-specified  time  span.  In  buffered  mode,  the  data  points  ;irc  inserted 
directly  into  the  appropriate  shared-memory  or  mapped-memory  data  arrays  by  sub- module. 

In  streaming  mode,  the  data  points  are  sent  to  the  Data  Output  Handler  for  IPC  transmission  to 
another  program. 

The  Attitude  and  Ephemeris  Decoders  read  the  Attitude  and  Ephemeris  files  and  make  this 
information  accessible  to  other  programs.  They  work  a  bit  differently  from  the  Telemetry 
Decoder  in  that  they  read  and  decode  the  entire  attitude  or  ephemeris  file  when  an  orbit  is  initial¬ 
ized.  The  attitude  and  ephemeris  data  can  then  be  accessed  at  will  by  the  Telcuieuy  Decoder  or 
others  without  reson  to  disk  I/O. 

The  Telemetry,  Attitude,  and  Ephemeris  Decoding  sub-modules  are  also  responsible  for  han¬ 
dling  orbit  overlap  when  time  spans  crossing  orbit  boundaries  are  specified.  Tf.ey  nrust  insure 
that  redundant  data  is  not  made  available  to  other  programs. 

4.3  Science  Control  Module: 

(See  figure  for  context) 
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The  purpose  of  the  CRRES  Science  Algorithm  Source  is  to  provide  computed  science  quanti¬ 
ties  to  user  programs  which  request  such  information.  In  the  "Fiche"  application  the  "Fiche"  User 
Interface  will  attach  to  the  CRRES  Science  Algorithm  Source  and  the  CRRES  Science  Algorithm 
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Source  will  in  turn  attach  to  the  CRRES  Raw  Data  Source.  These  three  programs  will  act  in  uni¬ 
son  to  provide  the  full,  extant  facilities  of  the  "Fiche  Program". 

The  process  of  linking  up  will  occur  something  like  this.  The  CRRES  Science  Algorithm 
Source  will  attach  to  the  "Fiche"  User  Interface,  identify  itself  and  pass  to  the  User  Interface  a  lis: 
of  data  which  the  CRRES  Science  Algorithm  Source  can  make  available  upon  request.  When  the 
User  Interface  passes  a  request  for  a  certain  science  quantity,  the  CRRES  Science  Algorithm 
Source  will  immediately  send  back  all  information  the  plotting  routine  will  need  to  set  up  the  plot 
frame. 

The  CRRES  Science  Algorithm  Source  will  in  turn  attach  to  the  CRRES  Raw  Data  Source  and 
obtain  the  raw  data  buffers  required  for  the  requested  quantity.  Then  it  will  perform  the  neces¬ 
sary  calculations  on  that  data  and  create  a  buffer  of  the  requested  quantity.  This  q  lanrity  data  will 
be  returned  to  the  User  Interface  asynchronously  as  it  becomes  available  so  that  it  can  be  plotted 
immediately. 

The  proposed  organization  of  the  CRRES  Science  Algorithm  Source  is  shown  in  figure  2.  The 
major  components  of  the  CRRES  Science  Algorithm  Source  number  10  and  are  listed  below. 
Each  is  explained  briefly  in  the  sections  which  follow. 

4.3.1.  User/Source  Interface 

4.3.2.  Source/Source  Interface  Plug 

4.3.3.  Source/Source  Interface  Socket 

4.3.4.  Source  Data  Module 

4.3.5.  Attach  Module 

4.3.6.  Info  Card  Decommutator 

4.3.7.  Plot  Request  Handler 

4.3.8.  Computing  Module 

4.3.9.  Data  Buffers 

4.3.10.  Data  Polling  Module 

4.3.1.  User/Source  Interface 

The  User/Source  Interface  will  be  a  connection  which  will  be  used  to  send  small  amounts  of 
data  between  what  is  known  as  a  "source",  a  provider  of  plottable  information,  and  w  hat  is  known 
as  a  "user",  a  process  which  utilizes  the  data  for  some  son  of  user  output.  Basic  sons  of  messages 
which  will  be  sent  from  the  User  to  the  Source  will  include  information  the  Source  requires  from 
the  user  to  operate  correctly  and  requests  for  plot  information/data.  The  sons  of  rnes.sages  which 
will  be  sent  from  the  Source  back  to  the  User  will  include  an  initiation  list  of  quantities  available 
from  the  Source  and  a  Source  name.  Specific  Plot  information,  and  the  asynchronous  plottable 
data  itself.  The  latter  will  comprise  the  majority  of  information  transferred  via  this  interface. 

4.3.2.  Source/Source  Interface  Plug 

The  Sourcc/Source  Interface  Plug  is  a  receiving  "pon"  for  data  from  another  Source  (i.e.  the 
CRRES  Raw  Data  Source).  This  pon  will  attach  to  available  Source(s)  and  make  available  to  the 
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CRRES  Science  Algorithm  Source  data  from  the  attached  source. 

A  key  element  of  this  Plug  is  that  it  will  provide  for  three  "modes"  of  operation;  Shared  Mem¬ 
ory,  which  is  the  primary  option.  Mapped  Memory,  and  Streamed  Data.  The  difference  between 
the  three  options  is  but  a  configuration  decision.  The  use  of  Shared  Memory  would  require  sys¬ 
tem  administrators  to  recompile  their  UNK  kernel  (operating  system)  to  allow  shared  memory 
segments  of  ten  megabytes.  Mapped  Memory  does  not  require  this,  but  requires  instead  that  a  35 
megabyte  file  be  created  on  one's  harddisk.  Streamed  Data  would  circumvent  both  of  these  down¬ 
falls,  but  would  also  cut  performance  considerably. 

4.3  J.  Source/Source  Interface  Socket 

The  Source/Source  Interface  Socket  is  quite  similar  to  the  Source/Source  Interface  Plug  except 
that  it  provides  access  for  other  Source  processes  to  the  CRRES  Science  Algorithm  Source  data. 
Another  Process  would  attach  to  this,  say,  if  it  wished  to  take  CRRES  Science  data  and  perform 
further  calculations  before  passing  the  data  on  to  a  User. 

4.3.4.  Source  Data  Module 

The  Source  Data  Module's  sole  purpose  is  to  provide  a  common  interface  for  the  CRRES  Sci¬ 
ence  Algorithms  to  other  Source  data  independent  of  the  Source/Source  Interface  mode  of  opera¬ 
tion. 

It  is  desirable  to  always  be  able  to  access  data  buffers  by  getting  some  limit  information  about 
the  amount  of  data  available  and  a  pointer  to  an  established  data  buffer.  In  this  manner  the 
CRRES  Science  Algorithms  are  freed  from  having  to  perform  unnecessary  and  messy  data  collec¬ 
tion  (event  driven  data  collection)  which  caused  so  many  problems  in  the  previous  version  of  the 
"Fiche"  software. 

In  particular,  this  is  not  a  problem  in  the  cases  of  using  Shared  or  Mapped  Memory.  A  pointer 
to  those  common  memory  locations  is  passed  and  the  data  is  accessed  trivially.  In  the  case  of 
Streamed  Data,  however,  data  will  be  coming  in  small  portions.  The  Source  Data  Module  will 
assemble  these  pieces  into  a  contiguous  data  buffer  and  header  information  and  return  the  header 
and  pointer  information  which  will  identically  match  the  Shared  and  Mapped  Memory  case. 

Note:  there  will  be  NO  event  driven  data  computations! 

4.3  J.  Attach  Module 

The  Attach  Module  has  a  relatively  small,  but  important  role  in  the  outlined  scheme.  It's  sole 
purpose  is  to  attach  to  any  other  matching  process.  The  term  attach  implies  that  it  will  first  of  all 
establish  a  firm  data  connection  between  this  Source  and  other  Sources  or  User  programs.  Once 
this  has  been  established  the  Attach  Module  will  exchange  with  that  process  any  necessary 
information  for  the  two  to  operate  in  unison.  As  an  example.  Attach  routine  will  recognize  the 
"Fiche "  User  Interface  process  and  form  a  (series  oO  data  link  and  handshaking  lines  with  it.  It 
will  then  pass  the  User  Interface  its  name  and  a  list  of  the  quantities  that  it  can  make  available. 
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Once  this  is  done  it  will  tell  the  User  Interface  that  it  must  have  a  timespan  before  any  data  can  be 
requested.  Once  this  is  done,  the  attach  module  goes  back  to  waiting  for  other  User  processes  to 
start  up  which  it  will  need  to  attach  to.  Any  further  processed  which  start-up  will  be  attached  to  in 
turn  in  a  similar  manner. 

4.3.6.  Info  Card  Decommutator 

The  Info  Card  Decommutator  has  but  one  function  and  that  is  to  parse  from  an  ASCII  file  the 
list  of  quantities  and  quantity  specific  plot  information  that  will  be  needed  to  provide  to  any  I  ser 
process  to  which  this  attaches  and  place  this  information  where  the  CRRES  Science  Algorithm 
Source  can  access  it.  This  location  will  be  known  as  the  Info  Card  Stack. 

4.3.7.  Plot  Request  Handler 

The  Plot  Request  Handler  will  receive  from  the  User/Source  Interface  Data  Requests  which 
originated  from  the  "Fiche"  User  Interface.  It  will  immediately  gather  the  plot  specific  informa¬ 
tion  for  the  requested  data  quantity  and  send  this  to  the  User/Source  Interface  to  be  forwarded  to 
the  "Fiche"  User  Interface.  It  will  then  relay  this  Data  Request  to  two  places;  the  Computing 
Module  so  that  the  desired  quantity(ies)  can  begin  to  be  calculated  and  to  the  Data 
Polling  Module  so  that  as  the  data  is  calculated  it  can  be  sent  off  to  the  "Fiche"  User  Interface  for 
'real-time'  plotting.  It  then  waits  for  another  Data  Request  to  come  in. 

4.3.8.  Computing  Module 

The  Compute  Module  is  the  main  stay  of  the  CRRES  Science  Algorithm  Source.  It  provides 
the  computational  engine  for  deriving  the  desired  quantities.  The  Compute  Module  will  receive 
timespan  information  from  the  "Fiche"  User  Interface  and  pass  this  on  to  the  decommutator  to 
make  available  the  raw  data  for  the  Scientific  Calculations.  It  will  receive  data  requests  from  the 
User  Interface  and  maintain  a  list  of  all  Science  Quantities  to  be  calculated,  and  it  will 
maintain  the  buffers  for  all  final  Science  Quantities  and  Intermediate  steps  so  that  redundant  com¬ 
putations  will  not  occur.  All  of  these  tasks  can  be  broken  down  into  several  functional  parts  (see 
figure  3).  These  are 

4.3.8. 1.  Data  Manager 

4.3. 8. 2.  Data  List 

4.3. 8.3.  Prepare  Data 

4. 3.8.4.  Build  All  Buffers 

4. 3. 8.5.  Data  Quantity  Handler 

Each  part  and  its  function  will  be  discussed  in  the  following  sections. 

4.3.8. 1.  Data  Manager 

The  Data  Manager  Routine  will  be  responsible  for  receiving  data  requests  (and  the  termina¬ 
tions  thereoO  from  the  User/Source  Interface  which  originated  in  the  "Fiche"  User  Interface  and 
will  use  these  to  maintain  a  list  of  all  scientific  quantities  which  must  be  computed.  In  addition  to 
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this  task,  when  a  new  quantity  (a  previously  unrequested  quantity  which  is  neither  the  result  nor 
an  intermediate  step  to  another  previously  requested  science  quantity)  is  requested,  the  Data 
Manager  will  signal  the  Prepare  Data  Routine  to  compute  this  quantity. 

4.3.8.2.  Data  List 

The  Data  List  will  be  maintained  by  the  Data  Manager.  This  list  will  include  all  information 
which  will  be  required  to  compute  the  given  science  quantity.  This  list  will  be  referenced  by  the 
Build  All  Buffers  routine  which  will  scroll  through  all  the  quantities  to  be  computed  and  do  so. 

4.3.8.3.  Prepare  Data 

By  far  the  most  important  routine  of  all.  The  Prepare  Data  routine  is  responsible  for  creating  a 
requested  science  quantity  either  from  scratch  or  from  an  intermediate  step  which  has  been  previ¬ 
ously  computed  for  another  science  quantity  for  this  timespan.  The  aim  of  this  routine  is  to  elim¬ 
inate  the  possibility  of  redundant  science  computations. 

The  first  step  (figure  4)  is  that  the  Prepare  Data  routine  will  receive  the  requested  quantity  from 
the  calling  routine.  It  will  then  check  with  the  Data  Quantity  Handler  to  see  if  it  exists.  If  it  does, 
then  the  action  is  trivial;  simply  return  the  pointer  to  the  existing  buffer.  If  it  does  not  exist  then  it 
will  get  the  list  of  building  blocks  (intermediate  steps  which  are  computed  on  the  way  to  building 
this  requested  quantity).  It  will  then  go  through  this  list  and  call  Prepare  Data  itself  for  each 
Building  Block  Quantity.  Prepare  Data  will  return  the  pointers  to  each  of  the  building  block  quan¬ 
tity  buffers  as  it  is  called  in  the  manner  that  is  being  described  here.  Once  all  the  building  block 
quantities  for  this  requested  quantity  are  gotten  (and  the  respective  data  buffers  built)  Prepare 
Data  will  call  the  "Compute  Function"  for  this  particular  quantity. 

The  "Compute  Function"  corresponds  to  the  actual  science  algorithm  calculation  (e.g.  Rotate 
Electric  Field,  Rotate  B  into  MGSE,  Free  form  Operators  and  so  on).  The  environment  of  the 
Compute  Function  is  that  it  receives  complete  buffers  for  the  timespan  for  which  it  is  concerned 
and  can  access  these  in  a  completely  random  fashion.  This  allows  great  flexibility  and  speed  for 
any  sort  of  science  algorithm  whether  it  simply  performs  a  point  by  point  computation  or  whether 
it  is  dependent  upon  past  and  future  values  for  the  given  computational  time.  The  Compute  Func¬ 
tion  will  be  the  focus  for  a  person  who  is  adding  a  science  quantity.  The  only  other  step  will  be 
setting  up  the  description  in  an  ASCII  file  for  the  building  block  list  and  plotting  information. 

4.3.8.4.  Build  All  Buffers 

The  Build  All  Buffers  will  be  responsible  for  re-creating  the  current  Data  List  of  requested 
quantities  from  scratch  when  necessary  (i.e.  a  new  timespan  is  received  from  the  User  Interface). 
It  will  do  this  by  first  using  the  Data  Quantity  Handler  to  throw  away  all  existing  buffers.  It  will 
then  go  through  the  Data  List  and  request  Prepare  Data  to  compute  each  of  the  requested  quanti¬ 
ties. 

4.3.8.5.  (DQH)  Data  Quantity  Handler 

see  section  4.4  Data  Quantity  Handler  (DQH)  Buffer  Module 
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The  Data  Quantity  Handler  may  be  cither  a  separate  program  or  simply  a  set  of  library  routiner 
which  will  maintain  the  Data  Buffers.  Ideally,  the  same  code  should  be  used  to  maintain  the 
CRRES  Science  Algorithm  Source's  Data  Buffers  as  is  used  to  maintain  the  CRRES  Raw  Data 
Source's  Data  Buffers. 

The  Data  Quantity  Handler  will  provide  facilities  for  adding,  deleting,  filling,  emptying,  read 
ing,  and  indexing  Data  Buffers.  All  values  (i.e.  size,  label)  should  be  dynamic  (passed  in  from 
the  outside  world). 

No  other  routines  will  directly  access  the  data  buffers  except  for  direct  random  access  reading. 

4.3.9.  Data  Buffers 

The  Data  Buffers  will  be  created  and  maintained  by  a  buffer  manager  library.  This  library  will 
be  called  by  the  Computing  Module  to  set  up  and  store  the  Data  Buffer  quantities  for  use  by  either 
other  Sources  through  the  Source  Data  Module  or  to  the  User  Interface  through  the  Data  Polling 
Module. 

4.3.10.  Data  Polling  Module 

The  Data  Polling  Module  receives  a  Data  Request  from  the  Plot  Request  Handler  which  has 
been  forwarded  down  from  the  "Fiche"  User  Interface.  This  routine  requests  a  buffer  of  the 
appropriate  size  from  the  DQH  Module  and  returns  this  pointer  to  the  calling  routine  so  that  the 
data  can  be  accessed  as  it  is  aeated  by  the  Computing  Module. 


All  of  these  sections  will  be  combined  in  one  process  which  will  be  accessed  as  an  entity  only 
through  the  Source/Source  Interface  or  the  User/Source  Interface.  No  other  access  will  be  allow¬ 
able  nor  necessary  to  properly  use  and  manipulate  the  CRRES  Science  Algorithm  Source. 


4.4  File  Export  and  Import  Facilities 

The  File  Export  and  Import  Facilities  will  be  a  series  of  separate  modules  which  are  as  separate 
in  software  as  they  are  in  function. 

Each  of  the  file  formats  will  have  a  module  which  will  encode  that  panicular  file  format.  Each 
of  these  in  turn  will  be  called  from  a  more  general  file  expon  module.  The  general  file  expon 
module  will  interface  with  the  Decommutator,  Science,  and  File  "sources"  in  the  same  manner  as 
the  User  Interface  does;  that  is  it  will  utilize  the  same  Inter-Process  Communication  protocol  and 
methodology  as  the  UI.  This  general  file  export  module  can  be  called  up  from  the  User  Interface 
or  the  Batch  Processor  and  will  then  be  spawned  off  as  its  own  process. 

Likewise,  the  Import  Facilities  will  have  a  module  which  will  decode  each  panicular  file  for¬ 
mat.  These  specific  decoders  will  be  called  from  a  more  general  file  import  module.  The  File 
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Import  Module  will  attach  in  the  same  manner  and  behave  to  the  software  exactly  the  same  as  any 
other  "source"  namely,  the  CRRES  Decommutator  and  the  Science  Control  Module. 


4.5  Data  Quantity  Handler  (DQH)  Buffer  Module: 

This  program  has  the  responsibility  of  providing  access  to  shared  data  between  the  various  sep¬ 
arate  programs  in  the  CRRES  software  package.  It  will  also  be  used  in  the  same  way  for  POLAR, 
CLUSTER,  and  FAST  data  handling. 

It  would  be  possible  to  have  each  separate  program  (the  CRRES  decommutator  and  the  science 
programs)  be  responsible  for  their  own  use  of  memory.  However,  it  is  architecturally  more  sound 
and  simple  to  focus  this  responsibility  on  a  single  program  for  many  of  the  reasons  listed  in  sec¬ 
tion  2.  It  also  opens  the  possibility  of  multiple  data  streams  into  a  CRRES  user  session.  One 
would  be  able  to  compare  CRRES  data  with,  say,  POLAR  data. 

4.5.1  DQH  Inputs: 

There  are  no  input  files  to  this  program.  The  only  inputs  are  quantity  descriptors,  which  the 
DQH  uses  to  keep  track  of  the  names  of  each  data  buffer.  These  are  transmitted  as  data  buffers 
are  requested  to  the  program  (via  EPC)  from  two  main  sources:  the  raw  instrument  quantity 
descriptors  from  the  decommutator  and  the  derived  scientific  quantity  descriptors  from  the  Sci¬ 
ence  Control  Module  (SCM).  These  programs  must  also  specify  how  large  the  associated  arrays 
must  be  for  each  quantity. 

4.5.2  How  the  DQH  Works: 

This  subsection  describes  the  sequence  of  events  which  result  in  system-available  data  arrays  in 
memory  for  use  by  other  programs. 

The  DQH  will  be  invoked  as  a  service  when  the  CRRES  software  is  started  on  a  workstation. 
One  of  the  parameters  used  to  invoke  the  DQH  is  an  indication  of  which  of  the  two  storage 
methods  (shared-memory  or  mapped-memory  files)  should  be  utilized.  The  DQH  is  then  ready 
for  buffer  requests. 

The  decommutator  is  given  a  time-span  to  decode  (from  the  User  Interface).  It  computes  how 
many  data  points  of  each  of  the  raw  instrument  quantities  it  will  produce  for  the  time  span  and 
then  sends  the  required  commands  including  the  particular  raw  data  descriptor  to  the  DQH  to 
have  it  allocate  the  necessary  buffer  storage  for  each  raw  quantity.  The  DQH  will  maintain  a  list 
of  internal  tables  which  store  this  information  and  allocate  a  buffer  for  each  request.  Similarly, 
the  SCM  will  pass  the  array  size  information  and  science  data  descriptors  to  the  DQH  for  alloca¬ 
tion.  Once  these  arrays  have  been  allocated  (either  shared-memory  or  memory-mapped  files),  any 
program  can  request  the  location  of  these  buffers  from  the  DQH.  The  decommutator  and  SCM 
will  request  this  information. 

When  the  CRRES  software  requests  a  new  time  span  from  the  decommutator,  it  is  checked  to 
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see  if  the  new  ame  qtan  is  a  subset  of  the  old.  If  not,  the  deconunutator  commands  the  DQH  to 
destroy  its  cunent  CRRES  buffers  and  the  above  cycle  is  repeated.  If  the  new  time  span  is  a  sub¬ 
set  of  the  old  (a  "zoom-in")  then  there  is  no  need  for  a  re-decommutation  cycle  and  the  old  buffers 
are  still  used.  Even  in  a  zoom-in,  however,  the  SCM  may  wish  to  have  the  science  quantity  buff 
ers  destroyed,  reallocated,  and  refilled.  This  can  be  controlled  from  the  UI. 

When  the  CRRES  session  is  ended,  the  DQH  is  commanded  to  destroy  the  buffers  and  go  back 
into  a  "sleep"  state  (waiting  for  the  next  service  request). 

4.5  J  Sub-modules  of  the  DQH: 

The  following  are  the  sub-modules  of  the  Data  Quantity  Handler: 

•  Interprocess  Communications  Handler 

•  Command/Request  Interpreter 

•  Buffer  Allocation  and  Maintenance  Handler 

The  Interprocess  Communications  Handler  is  the  same  set  of  library  routines  used  by  the 
CRRES  decommutator.  It  reads  and  writes  IPC  messages. 

The  Command/Request  sub-module  unpacks  and  parses  incoming  IPC  messages.  It  expects  to 
see  only  commands  and  requests  known  by  the  DQH,  When  it  parses  a  legitimate  command,  it 
passes  control  to  the  appropriate  subroutine  within  the  DQH. 

The  Buffer  Allocation  and  Maintenance  sub-module  is  the  major  ponion  of  the  program.  It 
deals  with  quantity  descriptors,  shared-memory  vs.  mapped  memory,  allocation  of  memory,  etc. 
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Contents  of  the  CRRES  Implementation  Document: 

The  "CRRES  Implementation  Document"  will  be  a  programmer's  level  of  documentation  on  the 
new  version  of  the  CRRES  software.  Its  purpose  is  to  document,  as  fully  as  possible,  all  aspects 
of  the  source  code  so  that  responsibility  of  program  maintenance  can  be  painlessly  shifted  to  new 
people.  This  document  will  be  generated  as  the  software  is  implemented  in  the  first  part  of  1992. 

Here  is  a  brief  description  of  the  contents  of  the  document: 

1.  An  introduction  which  will  briefly  describe  the  major  and  minor  component  programs  of  the 
software. 

2.  Detailed  definitions  of  the  important  data  abstractions  in  the  software  (quantity  descriptors, 
plot  descriptors,  etc).  The  level  of  documentation  will  include  actual  "C"-structure  listings,  with  a 
description  of  each  field  within  these  structures. 

3.  Definitions  of  the  command/request  functions  to  each  of  the  programs  in  the  software. 

4.  Detatiled  definition  of  the  inter-program  communications  protocol  and  functions  of  the  soft¬ 
ware.  TCP/IP  will  be  used  as  the  transmission  mechanism  but  our  own  internal  protocol  will 
encode  the  specific  commands  and  data  transfer  structures  within  TCP.  This  must  be  defined  in 
detail. 

5.  A  section  which  will  describe,  in  great  detail,  control  and  data  flow  during  a  typical  user  ses¬ 
sion  (how  and  when  the  various  sub-programs  are  used,  where  the  data  really  is,  when  computa¬ 
tions  are  triggered,  etc). 

6.  A  description  of  the  mechanism  for  allowing  user’s  to  write  and  connect  new  science  programs 
into  the  software.  The  "User's  Guide"  will  show  examples  of  how  this  is  done. 

7.  A  large  section  describing  the  interface  to  all  subroutines  in  the  programs  of  the  software.  This 
section  will  be  similar  to  the  Microsoft  "C-Compiler  Run  Time  Library  Manual".  Each  subrou¬ 
tine  will  have  about  a  page  describing  its  calling  sequence  and  an  example  of  use.  Those  subrou¬ 
tines  which  are  accessible  to  writers  of  science  "plug-in"  modules  will  have  "C"  and  "Fortran" 
interfaces  described. 

8.  Instructions  on  building  the  software  and  source-code  control. 
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New  CRRES  Implementation  Document 


I.  Introduction 

The  Implementatkm  Document  describes  in  detail  the  actual  composition  and  interactions  of  the 
New  Version  of  the  “Fiche”  Software.  It  accomplishes  this  by  discussing  the  Startup  and  Control 
process  of  the  software  modules,  discussing  the  inner-structure  of  each  major  module  of  the  soft¬ 
ware  (e.g.  Decommutator,  Science,  Data  Quantity  Handler,  User  Interface,  IPC),  discussing  the 
interactions  of  these  modules  in  a  typical  user  session,  the  methodology  behind  building  and 
maintaining  the  software,  the  data  objects  which  are  used  throughout  the  software,  and  finally  the 
description  in  detail  of  each  function  used  to  comprise  the  whole.  In  this  document,  these  sections 
are  developed  and  expanded.  The  hope  is  that  this  document  will  provide  all  the  necessary  infor¬ 
mation  for  a  new  programmer  or  scientist  wdth  software  experience  to  maintain,  modify  and 
expand  this  software. 
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I.  Introduction 


II.  Startup  and  Control 


This  section  will  describe  in  detail  the  method  in  which  the  major  software  modules  are  staned  up 
and  how  one  process  (The  User  Interface)  gains  “control”.  The  methods  that  have  been  discussed 
about  starting  the  processes  up  are 

1)  starting  all  the  necessary  processes  through  a  shell  script 

2)  having  the  user  interface  have  knowledge  of  the  other  modules  and  allow  the  user  to  start  them 
up. 

3)  having  a  startup  which  looks  and  acts  similar  to  the  Frame  Maker  startup  bar. 
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II.  Startup  and  Control 


in.  Module  Section 


This  section  will  describe  in  detail  the  major  modules  of  the  “Fiche”  Software.  Here  the  Software 
Developers  will  detail  the  specific  routines  which  comprise  each  module,  reference  them  in  the 
Function  Listing  Section,  and  show  how  they  interact  to  provide  complete  functionality  of  that 
module.  In  addition  the  developers  will  describe  the  data  passed  between  the  routines.  Finally,  the 
developers  will  describe  how  each  entire  module  interfaces  with  the  other  major  modules  and  will 
mention  the  data  abstractions  which  are  used  and  reference  them  in  the  Data  Abstraction  Section 

A.  User  Interface 

B.  Decommutator 

C.  Science 

D.  Data  Quantity  Handler 

E.  Interprocess  Communications 

F.  In-House  Libraries  (gob,  tooll,  toolm,  gsh,  decom,  and  so  on). 
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ID.  Module  Section 


IV.  User  Session  Description  Section 


TTie  User  Session  Description  Section  will  discuss  the  Above  described  interaction  for  the  specific 
instance  of  a  typical  user  session.  In  this,  the  developers  will  specify  specific  Data  Abstractions 
and  their  values  and  show  how  these  flow  through  the  software  as  a  whole  from  module  to  module 
and  routine  to  routine.  In  addition,  the  developers  will  describe  the  process  of  staning  the  pro¬ 
cesses  up  and  how  the  interact  to  form  a  functional  whole. 
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IV.  User  Session  Description  Section 


V.  Building  and  Maintaining  the  Software  Section 


This  section  will  describe  how  a  user  should  safe-guard  the  software  with  software  control  and 
how  the  user  should  go  about  building  an  executable  version  of  the  software  for  use  in  a  variety  of 
software  configurations.  Also  this  section  will  describe  how  to  configure  one’s  system  to  suppon 
this  software. 
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V.  Building  and  Maintaining  the  Software  ~xtion 


VI.  Data  Abstraction  Section 


The  Data  Abstraction  Section  will  describe  all  of  the  Data  Objects/Quantities  which  are  used  uni¬ 
versally  throughout  the  software.  This  description  will  describe  in  detail  the  memory  sizes  of  the 
data  types  and  the  contents  of  each  byte. 
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VI.  Data  Abstraction  Section 


VII.  Function  Listing  Section 


The  Function  Listing  Section  will  contain  an  alphabetical  listing  of  all  of  the  functions  in  the  soft 
ware  regardless  of  module  affiliation.  Each  of  the  listings  will  contain  a  description  of  each  func¬ 
tion  declaration  and  its  calling  parameters  and  return  values.  In  addition  there  will  be  listed  a 
pertinent  example  of  use  and  a  reference  as  to  where  it  may  be  found  in  the  actual  source  code 
files.  This  will  provide  future  software  developers  and  scientists  a  useful  tool  for  comprehending 
and  utilizing  tlw  software.  Reference  to  source  code. 

Copy  template  from  function. template: 
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Vn.  Function  Listing  Section 


function  name 


Summary 

include  files 

function  declaration 
function  parameter  declaration 

Description 

description 

caveats 

Return  Value 

return  value 

See  Also 

related  functions 

Example 

example  source  code  file  (main) 
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function  name 


VIII.  Conclusion:  Additions  and  Simple  Changes 

The  Conclusion  to  the  Implementation  Document  will  include  a  son  of  programmer  manual  will 
discuss  "how  to"  make  simple  changes  and  additions  to  the  'Fiche'  software  (i.e.  add  algorithms 
and  plots,  etc.)  in  a  very  regimented  straight  forward  manner. 
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